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Before You Begin 


Introduction 


Congratulations on selecting MS-DOS, the operating system that runs more 
applications on your DECstation personal computer than any other compara- 
ble operating system. Before installing MS-DOS on your DECstation per- 
sonal computer, you should read the following introductory material. 


Remember, your Digital sales representative is always available to provide 
assistance and training. 


Note: The documentation contained in this software kit assumes that your 
DECstation hardware is installed properly. 


Ifyou need to set up your DECstation personal computer hardware, refer to 
your installation and operation manual before using this software kit. 


What is MS-DOS? 


Your DECstation personal computer’s disk operating system is MS-DOS. An 
operating system is a group of programs that manages the various parts of 
your computer — the main unit, the monitor, and any peripheral equipment 
such as a printer. A disk operating system (DOS) can direct information to 
disk drives and interpret information received from the drives. 


This version of MS-DOS supports networking, multiple MS-DOS partitions 
on your hard disk, virtual disk in main memory, 3.5-inch diskette drives, and 
many other storage devices. 


Before You Begin 


Kit Contents 


The following table describes the items in this software kit: 


Ce E 


DECstation Describes all new files and enhanced files (those files 
Enhancements that have been added or changed for use with DEC- 

station computers). Includes helpful notes about vari- 
ous MS-DOS commands and concepts. 












Microsoft MS-DOS 
User’s Guide 


Provides an introduction to the basic operations of 
MS-DOS, including how to start MS-DOS, copy disk- 
ettes, and use basic MS-DOS commands. 











Microsoft MS-DOS 
User’s Reference 


Is aresource manual that explains how to manipulate 
files and directories, use MS-DOS commands, create 
and use batch files, use the line editor, debug files, 
configure your system, install device drivers, and use 
code pages. A directory of MS-DOS messages is also 
included. 


Microsoft GW-BASIC Helps you use the GW-BASIC interpreter with the 
User’s Guide MS-DOS operating system. 


Microsoft GW-BASIC Provides an alphabetical reference to GW-BASIC in- 
User’s Reference structions. 


Two 3.5-inch diskettes The MS-DOS Startup and Operating diskette and the 
MS-DOS Operating diskette. 
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Getting Started 


The following procedure outlines the general steps you need to perform to get 
your DECstation computer ready for use with MS-DOS. The specific steps 
you will take depend on several factors, including your system configuration, 
hard disk type (ST506 or SCSI), and keyboard type (LK250 or enhanced). 


1. Setup the hardware. 


See your computer’s installation and operation manual for complete 
hardware setup instructions. 


Note: Any time you change your system configuration (by adding 
optional disk drives and memory, for example), you need to run a 
setup utility to store the new configuration information in the com- 
puter. Your installation and operation manual tells you how to do 
this, also. 


2. Hard format (low-level format) the hard disk if it is not already formatted. 


Hard formatting is the first step in preparing a hard disk for infor- 
mation storage. If you have an ST506 hard disk drive, use the 
Format Hard Disk utility on the Utilities diskette to perform the 
hard format. If you have a SCSI hard disk, do not use this utility. 
SCSI drives either are hard formatted at the factory or come with 
their own hard format utility and formatting instructions. 


3. Partition the hard disk. 


Write protect your MS-DOS diskettes, and start up the computer 
with the MS-DOS Startup and Operating diskette (Diskette 1 of 2) 
in drive A. Then, use the MS-DOS fdisk command to partition the 
hard disk. Fdisk is described in detail in Appendix D in the MS- 
DOS User’s Reference. 


Note: The Microsoft MS-DOS User’s Guide contains incorrect infor- 
mation about write protecting 3.5-inch diskettes. A 3.5-inch diskette 
is write protected when the built-in tab does not cover the rectan- 
gular write-protection hole. Your computer’s installation and operation 
manual provides complete hardware setup instructions. 


Before You Begin 


4. Soft format the hard disk. 


The soft format will be performed automatically when you install 
MS-DOS in Step 5. 


5. Runthedecselec or select command to finish formatting the hard disk and 
begin installing MS-DOS on it. 


Decselec and select both: 
¢ Soft format the hard disk 


+ Create the files autoexec.bat and config.sys, which contain startup 
information for MS-DOS 


- Copy the contents of the MS-DOS Startup and Operating diskette 
(Diskette 1) to asubdirectory on the hard disk 


Which command you use depends on your keyboard. Use the 
decselec command with an LK250 keyboard. Use the standard MS- 
DOS select command with any other keyboard. Both commands 
install MS-DOS with the desired country-specific information and 
keyboard layout. 

For information on using decselec, see DECstation Enhancements. 
For information on using select, see the MS-DOS User’s Reference. 
Note that both commands are on the MS-DOS Startup and Operat- 
ing diskette (Diskette 1) and this diskette must be in drive A when 
you enter the command. 


6. Copy the contents of the MS-DOS Operating diskette (Diskette 2) to the 
same directory to which you copied the contents of Diskette 1. 


Insert the MS-DOS Operating diskette (Diskette 2) into drive A, 
and type the command in the form: 
copy a:*.* c:\dosdir ENTER 


where: 
dosdir is the name of the sudirectory into which you copied the 
other MS-DOS files in Step 5. 


Where to Go from Here 


Once MS-DOS is on your hard disk, you can start the operating system 
without using the MS-DOS diskettes. Simply turn on the computer, and 
MS-DOS will start up from the hard disk. 
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About This Manual 


Before You Use MS-DOS 


Your DECstation MS-DOS operating system diskettes contain four types of 
files: 


¢ Thestandard MS-DOS Version 3.3 files from Microsoft Corporation 


e Microsoft MS-DOS files that have been enhanced for use with DEC- 
station computers 


« NewMS-DOS files 
+ GW-BASIC files 


This manual describes all the new files and any enhanced files that require 
new documentation. Before using any MS-DOS command or device driver, 
check to see whether it appears in this manual. Ifit does, the description will 
indicate whether the information is newor should replace information in the 
Microsoft MS-DOS User’s Reference. 


Also included are two sections called “MS-DOS Notes” and “BASIC Notes.” 
These sections clarify some commands and concepts covered in Microsoft’s 
MS-DOS and GW-BASIC manuals. Use the notes in conjunction with those 
manuals. 


Before You Use This Manual 


This manual is a reference manual. It assumes you are familiar with basic 
MS-DOS terminology, concepts, and procedures — including how to start 
MS-DOS and how to copy diskettes. Ifyou are new to MS-DOS, you should 
Start with Before You Begin and the Microsoft MS-DOS User’s Guide, an 
easy-to-follow introduction to MS-DOS. 


Once you are familiar with MS-DOS, you should refer to this manual for 
information about a particular command or device driver. 
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Typeface Conventions 


For your convenience, this manual uses the same typeface conventions as the 
Microsoft MS-DOS User’s Reference: 


In body text: 

Convention Is used for 

bold Command names 

Screen type Examples and information that appears on the 
screen 

SMALL CAPS BOLD Keys and key combinations 


Key combinations are keys that you press simultaneously. For example, to 
reset the computer, you hold down CTRL and press ALT and DEL at the same 
time. Key combinations are indicated with plus signs, for example, 
CTRL+ALT+DEL 


In command syntaxes: 


Convention Is used to indicate that 


bold You must type the item exactly as shown in the syntax line. 

italics The item is a variable for which you supply text. For example, 
when filename appears, type the name of the file you are 
referring to. 


[brackets] The item in the brackets is optional. To include the item, type 
only the information within the brackets. Do not type the 
brackets. 


e You can repeat the item as many times as necessary. 


Unless otherwise specified, you must use spaces to separate commands from 
their options, for example: 


deckeyb /d 


New / Enhanced Commands 


Use the information in this section in conjunction with Chapter 3 in the 
Microsoft MS-DOS User's Reference. The following table summarizes all the 
new or enhanced MS-DOS commands: 


Command 


attrib 
backlist 
backup 
dc 
deckeyb 
decmode 


decmouse 


decselec 


diskopt 
format; 
graphics 


keybrd 
modet 


rcrypt 
restore 
spooler 
xonxoff 


Purpose 


Sets, clears, or displays a file’s attributes. 

Displays files copied during a backup operation. 
Backs up one or more files from one disk to another. 
Compresses or decompresses a file. 

Loads an LK250 keyboard map file into memory. 


Sets operation modes for certain printer, video, communi- 
cations, and keyboard options. 


Lets a Digital mouse connected toa DEPCA board emulate 
a Microsoft mouse. 


Installs MS-DOS on a disk with the desired country- 
specific information and keyboard layout; for use with the 
Digital LK250 keyboard. 


Optimizes disk file storage. 
Formats a disk to receive MS-DOS files. 


Prepares MS-DOS for printer graphics on a DECstation 
printer. 


Loads the LK250 keyboard program. 


Sets operation modes for certain devices. Allows options 
such as code page support, display adapter switching, and 
printer redirection. 


Encrypts or decrypts a file. 
Restores backed up files. 
Sets the print spool parameters. 


Provides support for asynchronous (RS232) ports that 
have communications and attached serial printers that use 
the xon/xoff protocol. 
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Attrib 


This is an enhanced command. Use the following information instead of the 
information in the Microsoft MS-DOS User’s Reference. 


Purpose: 

Sets, clears, or displays the attributes of selected files in a directory. 
Syntax: 

attrib [[drive:][pathname]|[...][+; - [a] [s] [h] [r]][/L][/s]] 

or 


attrib [[+ ! — [a][s][h][r][x]][/L][/s]] [drive:][pathname][...] 


where: 
+ enables an attribute (a, s, h, or r). 


- disables an attribute (a, s, h, or r). 
a specifies the archive attribute. 


s specifies the system attribute. A system file makes up part of the MS-DOS 
operating system. 

h specifies the hidden attribute. You cannot see a hidden file when you use the 
dir command. 


r specifies the read-only attribute. You can read and execute a read-only file, 
but you cannot change or delete it. 


Comments: 


The drive: and pathname parameters specify the location of the file or files 
you want to reference. You can type the attributes either before or after the 
pathname. The attrib command accepts the following switches: 


Switch Purpose 
/s Processes all subdirectories as well as the specified path. 
/L Sends a log ofall program activity to the screen. 


You can use either the plus sign (+) or the minus sign (-) with an attribute. 
You cannot use both at the same time with the same attribute. 
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Attrib 


Notes: 


In addition to displaying and changing a file’s attributes, the attrib command 
can be used to find a file on a disk. From the root directory, use the format 
attrib filename /s. MS-DOS displays the attributes and the file’s complete 
pathname. 


Examples: 
To display the attrib help message, type: 
attrib 


To display the attributes of memo. txt, type: 
attrib memo.txt 


To set memo.t to archived, hidden, system, and read-only, type: 
attrib memo.txt +ashr 


Or attrib memo.txt +at+sthtr 


OF attrib memo.txt +a +s th +r 


To set memo.txt to system and read-only and clear it of the archive and hidden 
attributes, type: 

attrib +sr -ah 
The following command sets the archive bit for all .żxt files in the current 
directory and all subordinate subdirectories: 

attrib *.txt +a /s /L 


The screen displays an activity log as each file is modified. 
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Backlist 


This is anew command. 

Purpose: 

Displays the files copied during a backup operation. 
Syntax: 

backlist drive:[path] [/s:n[...]] 


where: 
drive: is the drive containing the backup (copied) files. 


path is the path containing the backup files. This is the directory containing 
the subdirectory bksubdir on a hard disk or virtual disk. If you omit path, the 
backlist command uses the default directory on the specified drive. 


Comments: 
The backlist command accepts the following switch: 


Switch Purpose 
Isin [e] Sorts the output list in the order specified byn. The first option 


specified is the primary sort option, the second, the secondary 
sort option, and so on. Do not insert spaces between the options. 
Ifyou specify duplicate options, only the first occurrence of that 
option determines its priority. 


The order specified byn can be one or more of the following: 


d Sorts by file modification date 


e Sorts by file extension 

f Sorts by filename 

p Sorts by path (directory) 

s Sorts by file size 

t Sorts by file modification time 

v__ Sorts by diskette volume number 
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Backlist 


Examples: 


Assume you had used backup to copy all drive C files to drive D. You can 
then display the backed up files on drive D by typing: 


backlist d: 
To display the backed up files, sorted by filename, type: 
backlist d: /s:f 


To display the backlist help message, type: 
backlist 
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Backup 


This is an enhanced command. Use the following information instead of the 
information in the Microsoft MS-DOS User’s Reference. 


Purpose: 
Backs up files from one disk to another. 


Syntax: 


backup drivel:[path1][filename] drive2:[path2] [/a}{/s][/m]|[/d:date] 
[/tstime] [/f] [/L|:drive:\path\filename]] 


where: 
drivel: is any logical drive containing the file(s) you want to back up, and 
filename specifies the file(s). You can use a wildcard in place of filename. 


drive2: is the drive to receive the file(s). It can be any logical drive on your 
workstation (RAM disk, hard disk drive, network drive, virtual disk, or 
diskette). 


path2 is the directory to receive the file(s). If you back up to a diskette, the 
backup command uses the root directory. If you back up to a hard disk or 
virtual disk and omit path2, the backup command creates the subdirectory 
bksubdir in the working directory on the default drive. If you specify path2, 
the backup command creates the subdirectory bksubdir in path2. 


Comments: 


In addition to backing up files to local drives, the backup command allows 
you to back up files to network drives and virtual disks. 


Using the backup command, you can periodically make an extra copy of files 
on a disk, reformat the disk, and restore the files using the restore command. 
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Backup 


The backup command accepts the following switches: 


Switch 


/a 


Is 


/m 


/d:date 


/tstime 


/f 


/Lidrive:\path\filename 


Purpose 


Adds files to the current contents of the backup 
disk without erasing the existing files on the disk. 
If there are no backup files on the target disk, the 
message Target cannot be used for 
backup is displayed. 


Backs up all subdirectories of the specified path. 


Backs up only those files that were modified since 
the last backup procedure. 


Backs up only those files that were modified on or 
after the specified date. The date format depends 
on the country code. See Appendix E in the 
Microsoft MS-DOS User’s Reference for specific 
date formats. 


Backs up only those files that were modified on or 
after the specified time. The time must be entered 
in the 24-hour format. The time format depends on 
your country code, and the time separators are 
country-dependent. See Appendix E in the 
Microsoft MS-DOS User’s Reference for specific 
time formats. 


Formats the target disk, if it is not already format- 
ted, using the drive’s native format (for example, 
a high-capacity format if it is a high-capacity 
drive). 


Creates a file to which a log ofall backup activity 
is sent. You must either include all three specifiers 
(drive, path, and filename) or omit all three. Ifyou 
omit drive, path, and filename, the backup com- 
mand creates the file backup./og in the root direc- 
tory of the source drive. If backup.log already 
exists, the backup command appends new infor- 
mation to the end of the file. The drive should not 
be the target drive. 
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Backup 


Notes: 


e The backup command erases all files in the target directory (on a hard 
disk) or in the root directory (on a diskette). 


e Youcan back up files from one diskette to another diskette, even if the 
diskettes have a different number of sectors and sides. 


¢  Youcan back up files from one hard disk partition to another hard disk 
partition, or to a subdirectory on a hard disk or network drive. You must 
run the restore command to retrieve files you backed up before you can 
use them. 


¢ Ifyou back up the hidden system files using the backup command, the 
restore command does not restore them. 


e Ifyou back up files to a hard disk or a virtual disk and run out of space, 
you have to find another place to store the backup files. You also have to 
perform the backup procedure again. 


e Ifyou backed up files using the MS-DOS Version 3.3 backup program, 
use the MS-DOS Version 3.3 restore program to restore them. 


¢  Ifappend /x is loaded, use append with a semicolon (append ;) to cancel 
previous append operations before using the backup command. 


Examples: 

To back up all files in the root directory of drive C to drive A, type: 
backup c:\*.* a:\ 

The screen displays a message prompting you to insert the first backup 

diskette into drive A. Insert a blank, formatted diskette and press ENTER. 


If you want a permanent list of the files you saved, use /L with the backup 
command. You can then type or print the log file. 


To back up all files in all directories on drive C to drive A, type: 

backup c:\*.* a: /s 
To back up to drive A all drive C root directory files that were modified since 
the last backup procedure, type: 

backup c:\*.* a: /m 
To back up all files in the root directory on drive A to the working directory 
on network drive I, type: 

backup az:\*.* is 
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De 


This is anew command. 
Purpose: 


Compresses files so that they use less disk space and require less transfer 
time. Also returns compressed files to their normal state. 


Syntax: 
de [/c}|/d][/q][ pathname] 


where: 
pathname is the file or group of files (specified by wildcards) to compress or 
decompress. 


Comments: 
De accepts the following switches: 


Switch Purpose 

Ie Causes de to compress a file. If the file is already compressed, 
de does not change it. 

/d Causes de to decompress a file. If the file is not compressed, 
dc does not change it. 

/q Displays a message indicating whether or not the specified file 


is compressed. No compressing or decompressing takes place. 


Notes: 


e Usedc to compress a file to save disk storage space, to reduce the time it 
takes to transfer or copy the file, or for archival purposes. The file you are 
compressing should be at least 600 bytes long. 


e Dcuses a modified LEMPEL-ZIV algorithm that replaces certain byte 
patterns with codes. As it reads a file, dc creates a table of byte patterns 
and the codes representing each pattern. For decompression, the program 
reads the table, converts the code to its original state, and then removes 
the table. 


e The degree of compression you can achieve depends on the length of the 
file and on the type of data in the file. De can compress text and data files 
by 40 to 60 percent. It compresses binary data files, such as.exe and.com 
files, less than 20 percent. 
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De 


¢ Ifyou do not specify a switch, de compresses standard files and decom- 
presses files that are compressed. 


« Ifthe contents of the file you specify are such that de cannot compress 
them, it does not change the file. 


Examples: 


Suppose you had a file called myfile.doc, located in the working directory. 
The following command would compress it: 


dc /c myfile.doc 


The following command would decompress a file named myfile.doc, located 
in the relate directory of drive A: 


dc /d a:\relate\myfile.doc 


This command would compress all files having an extension of .txt that reside 
in the working directory: 


de /c *.txt 
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Deckeyb 


This is anew command. 


Purpose: 


Loads a keyboard map file into memory. Use this command with the 
Digital LK250 keyboard. Use the keyb command with any other keyboard. 


Syntax: 


deckeyb [drive:|[pathname] 
deckeyb [/d] 


where: 
drive: specifies the drive containing the keyboard map file. If you omit the 
drive, the current drive is used. 


pathname specifies the keyboard map file you want to load. If you omit the 

path, the deckeyb command searches the working directory, any appended 
directories, the root directory, and the working search path. Ifyou omit a file 
extension,.key is used. 


Comments: 
The deckeyb command accepts the following switch: 


Switch Purpose 
/d Loads the default keyboard map file (stdus.key). 
Notes: 


¢ Thedecseleccommand automatically adds the deckeyb command to your 
autoexec.bat file, so you do not need to use deckeyb with decselec. 


e ‘You must run the keybrd command before you can use the deckeyb 
command. 


e Ifthe MS-DOS operating system finds the file and it is a valid keyboard 
map file, the deckeyb program loads the file into memory. The changes 
are implemented immediately. If the. key file is not in the proper format, 
a message is displayed and the keyboard is not modified. 


¢ Ifyou omit a filename, the deckeyb command displays a help screen. 
« Donotuse thedeckeyb command from MS-Windows. 
¢ Thedeckeyb command does not support code pages. 
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Deckeyb 


Pressing CTRL+ALT+F2 changes the currently loaded keyboard file to the 
default keyboard file, stdus.key. Pressing CTRL+ALT+F3 changes the 
currently loaded keyboard file to the last keyboard file loaded into 
memory. To activate this feature, be sure you have loaded a non-standard 
keyboard, such as stdfr. key. 


Note: The deckeyb command does not check to see that the font, 
keyboard, and country-specific information match. If they do not 
match, the results are unpredictable. 


To produce an accented (or umlauted) character that does not appear on 
the LK250 keyboard, type the accent key and then the letter key. For 
example, to produce the character á on a German LK250 keyboard, type 
“ andthen a Note that the accent key is called a dead key because it does 
not produce a character when used alone. 


Examples: 


To display the deckeyb help message, type: 


deckeyb 


To load the default keyboard file, type: 


deckeyb /d 


The screen displays a message confirming that the default keyboard map file 
has been successfully loaded. 


Pressing CTRL+ALT+F2 is another way to load the default keyboard file. 
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This is anew command. 
Purpose: 


Sets operation modes for certain printer, video, communications, and key- 
board device options. 


Use the decmode command when you want to use one of the options de- 
scribed below. Use the standard MS-DOS mode command for options such as 
code page support, switching display adapters, and printer redirection. 
Decmode does not support code pages. 


With a Digital LK250 keyboard, you must execute the keybrd command 
before using the decmode command to set the keyboard mode. 


Syntax: 
Help mode: 
decmode help [subject] 
demod [?] [subject] 
deiode [subject] [?] 
Printer mode: 
decmode lptn[:][type, width, Ipi, retry, qual, bold] 
Video mode: 
decmode vidmode 
Communications setup: 
decmode COMn[:][[baud, parity, databits, stopbits,] retry, bypass] 
Keyboard mode: 
decmode [keymode]|,bufsize] 
Comments: 


Because some decmode functions require the xonxoff command to be exe- 
cuted before running the decmode command, put the xonxoff command into 
your autoexec.bat file before running the decmode command. 


Do not use the decmode command from MS- Windows. 
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Help Mode 


The help mode function displays a list of options and the correct syntax for 
the decmode command. 


Type the command as follows: 


decmode help [subject] 
or 

decmode [?] [subject] 
or 

decmode [subject] [?] 


where: 
subject is the subject for which you want help: 


Help 

Option Purpose 

comm Displays a help screen for the communication parameter 
commands. 

print Displays a help screen for the printer setup commands. 

video Displays a help screen for the video mode commands. 

key Displays a help screen for the keyboard mode commands (only 


with a Digital LK250 keyboard). 


Examples: 


To display the topics for which help is available, type: 
decmode 


To display help information for printer setup commands, type: 
decmode help print 
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Printer Setup 
Printer setup enables you to set up any of the supported printers: 


Digital LA50 printer 

Digital LA75 Companion printer 

Digital LNO3 Printer (with or without a cartridge) 
Digital LA210 Letterprinter 

Digital LJ250 Companion Color Printer 

IBM Proprinter (type STD) 

IBM PC Color Printer (COLOR4 and COLOR8) 


Type the command in this format: 
decmode Iptn[:|[type, width, Ipi, retry, qual, bold] 


Option Purpose 
n Is a parallel port number (1, 2, 3, or 4). 


type Is a printer type (LA50, LA75, LA7S5STD, LA7S5DEC, LNO3, 
LNO3STD, LNO3DEC, LA210STD, LA210DEC, LJ250HP, 
LJ250DEC, STD, COLOR4, COLORS). 


If this parameter is present, the decmode command sets the 
printer type for the specified port. If this parameter is not 
present, the decmode command determines the type from the 
working setting. 


If the type is unknown but needed, the decmode command 
displays the valid printer types for you. Ifyou specify a printer 
type, the decmode command sends the appropriate escape 
sequence to the printer. If you type LA75, LA75STD, 
LA7SDEC, LA210STD, LA210DEC, LJ250HP, or LJ250DEC, 
the decmode command forces the printer into the appropriate 
mode. 


The LA75DEC, LA210DEC, LNO3, and LNO3DEC are treated 
as LA50-type printers. The LA75, LA75STD, LA210STD, and 
LNO3STD are treated as STD-type printers. 


width Is the number of characters per line (80, 96, or 132). If the printer 
type is STD, LA75, LA7S5STD, LA210STD, LNO3STD, 
COLOR4, or COLOR§, only 80 or 132 characters per line is 
valid. 
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lpi Is the number of lines per inch (6 or 8). 

retry Enables or disables continuous retries (p or -). 

p Enables continuous retry on timeouts; in other words, it keeps 
sending forever. 


- Disables continuous retry on timeouts; in other words, it 
attempts to send only once. If you omit this parameter, the 
working setting stays the same. Ifthe printer has been redirected 
to a communications port, retry is enabled on that 
communications port. 


qual Is the quality of print (d for draft quality, e for enhanced quality, 
or h for high quality). If the printer type is STD, LA75, 
LA75STD, LA210STD, LNO3STD, COLOR4, or COLORS, 
only draft and enhanced are valid. 


bold specifies the weight of the type (b for bold or n for normal). 
Notes: 


e Youcan set print quality and bolding for some, but not all, printer types. 
For more information about setting print quality and bolding for your 
printer, see your printer manual. 

e  Ifthespecified printer type refers to a network printer that is not ready, 
the Printer not ready message may take as long as ten minutes 
to appear. 

e Youcan use PRN in place of LPT1, AUX in place of COM1, and LA75 
in place of LA75STD. 


e Youcan specify the parameters in any order. 


e You mustrun the xonxoff command before setting the printer type. For 
more information, see “Xonxoff.” 
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Examples: 


To display the decmode printer setup help message, type: 
decmode help print 


To set up the LA75 printer for use, type: 
decmode LPT1:LA75 


The screen displays a message confirming that the printer type is set. 


To set up the LA75 printer for 80 columns, 8 lines per inch, continuous retry, 
draft quality, and normal weight, type: 


decmode LPT1:LA75,80,8,p,d,n 
The screen displays a message confirming that the printer has been success- 
fully programmed to the specified settings. 


To set up the LA75 printer in the “other” protocol mode, using xon/off to 
improve handshaking, type: 


decmode LPT1:=COM1: 
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Video Mode 

Video mode enables you to select the screen parameters. 

Use the vidmode option with the decmode command as shown: 


decmode vidmode 


where: 

vidmode is one of the following: 
40 Set to 40 columns, colors unchanged. 
80 Set to 80 columns, colors unchanged. 
BW40 Set to text mode, 40 columns, 2 colors. 
CO40 Set to text mode, 40 columns, 4 colors. 
BWS80 Set to text mode, 80 columns, 2 colors. 
CO80 Set to text mode, 80 columns, 4 colors. 
BW320 Set to 320 x 200 pixels, 2 colors. 
CO320 Set to 320 x 200 pixels, 4 colors. 
BW640 Set to 640 x 200 pixels, 2 colors. 
MONO Set up for monochrome mode. 


Selecting 40 or 80 affects the number of characters per line. The 40 and 80 
options are valid only in text modes. There is no effect with the monochrome 
adapter except to clear the screen. 


MONOshould only be used with monochrome monitors. 
All video modes, except MONO, are for a COLOR/graphics monitor adapter. 


Notes: 


¢ To shift the display right or left, use the mode command instead of 
decmode. 


¢ Toswitch between two connected monitors, use the mode command. 


Examples: 


To display the decmode video mode help message, type: 
decmode help video 


To set the video to 320 x 200 pixels with color enabled, type: 
decmode C0320 


The screen displays: 
Video mode set successfully. 
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Communications Setup 


Communications setup enables you to set the parameters for the serial ports 
and communications ports. 


Enter thedecmode command in this format: 
decmode COMn[:][[baud, parity, databits, stopbits,| retry, bypass] 


Option 
n 
baud 


parity 


databits 


stopbits 


retry 


bypass 


Purpose 
Is a serial port number (1, 2, 3, or 4). 


Is the baud rate (50, 75, 110, 134.5, 150, 300, 600, 1200 , 1800, 
2000, 2400, 3600, 4800, 7200, 9600, 19200). The default is 
1200. If you change parity, databits, or stopbits and do not 
change baud, baud is reset to its default value. 


Is e for even, o for odd, or n for none. If you change baud, 
databits, or stopbits and do not change parity, parity is reset to 
the default value (e). 


Is the number of data bits (5, 6, 7 or 8). The default is 7. Ifyou 
change baud, parity, or stopbits and do not change databits, 
databits is reset to the default value. 


Is the number ofstop bits (1 or 2). The default is 2 for 110 baud 
and 1 for all others. If you change baud, parity, or databits and 
do not change stopbits, stopbits is reset to the default value. 


Enables (p) or disables (-) continuous retries for a serial printer. 
The default is disabled (-). Ifyou use p, it keeps sending forever. 
If you use -, it sends only once. 


Bypasses the modem control signals coming into a port. 
Normally, modem control signals are used (bypass = m). 
The bypass value can be b or m: 


b Bypasses modem control signals. 
m Uses modem control signals. 


When using the xon/xoff protocol, be sure modem control signals are dis- 
abled. You must run the xonxoff command before you disable modem control 


signals. 
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Notes: 

You can specify the parameters in any order. They must be separated by one 
or more commas. Extra commas can precede or follow any parameter. 
Examples: 

To display the decmode communications setup help message, type: 


decmode help com 


Toset up communications port 1 for 1200 baud, even parity, 7 data bits, 1 stop 
bit, continuous retry, and bypass modem control, type: 


decmode coml1:1200,e,7,1,p,b 


The screen displays a message confirming that the serial port has been 
successfully programmed. 
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Keyboard Mode 


Keyboard mode enables you to change the keyboard mode and the keyboard 
buffer size. Initially the default settings are modified mode and 16 bytes for 
the buffer. 


Type the decmode command in the following format: 
decmode [keymode]|,bufsize] 


Option Purpose 


keymode Can be m to disable Digital extended keys or u to enable Digital 
extended keys. Digital extended keys are F11 through F20 and 
the special editing keypad. 


M is the default. If you omit keymode, it stays the same. You 
can toggle these modes by pressing ALT+F17. 


bufsize Is the size of the new keyboard buffer (1-80 characters). If you 
omit bufsize, it remains unchanged. If the buffer size is 16, the 
default buffer is selected. 


Notes: 


¢ The option to change the keyboard mode or keyboard buffer size should 
be used only with a Digital LK250 keyboard. 


+ ‘You mustrun the keybrd command before setting the keyboard mode or 
buffer size. See “Keybrd.” 


Examples: 
To display the decmode keyboard mode help message, type: 
decmode help key 


To set the keyboard to use Digital extended keys, type: 
decmode u 


The screen displays a message confirming that the keyboard mode has been 
set successfully. 


To set the keyboard to use Digital extended keys and specify a buffer of 80 
characters, type: 


decmode u,80 
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This is anew command. 


Purpose: 


Enables you to make the Digital mouse, used with a DEPCA board, emulate 
the Microsoft mouse. The decmouse command allows many applications that 
assume a Microsoft mouse is present to run with a Digital mouse. 


Syntax: 
decmouse 
Comments: 


To install decmouse on your system, you must add the following line to your 
config.sys file: 


device=c:\system\decmouse.sys 
Then, to use your Digital mouse, type decmouse at the system prompt 
before running the application. 
Notes: 


Ifyou unplug your mouse and then plug it back in after running the decmouse 
command, it does not work. To reactivate the mouse, reset your computer by 
pressing CTRL+ALT+DEL. 


Examples: 
To load decmouse.com as you need it, type: 
decmouse 
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This is anewcommand. 
Purpose: 


Installs MS-DOS on a disk with the desired country-specific information 
(such as date and time formats and collating sequence) for a selected country. 


Syntax: 
decselec [drivel:| [drive2:][path] yyy pathname 


where: 
drive]: is the source drive. 


drive2: is the target drive. 

path is the target subdirectory. 

Comments: 

The decselec command does the following: 

¢ Formats the target disk 

e Creates both the config. sys and the autoexec.bat files on the new disk 
e Copies the contents of the source disk to the target disk 


The source drive can be either drive A or drive B. The default source is drive 
A. The default target is drive B. 


If you choose a hard disk as the target, MS-DOS prompts you to type the 
correct volume label for that disk. If you type the wrong label, decselec ends. 


If you type the correct label, decselec displays a warning that it will erase all 
data on the hard disk. 


If you type N (for No), decselec ends. If you type Y (for yes), decselec 
formats the hard disk. 


You can use the following options with the decselec command: 


Option Purpose 


yyy Specifies the country code. MS-DOS gathers country-specific 
information such as date and time formats from the country. sys 
file for the country code specified. 


pathname Specifies the keyboard map file to load. 
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The country codes are as follows: 


Country or Language Country Code 
Code Page 

United States 001 437,850 
French Canada 002 863,850 
Latin American 003 437,850 
Netherlands 031 437,850 
Belgium 032 437,850 
France 033 437,850 
Spain 034 437,850 
Italy 039 437,850 
Switzerland 041 437,850 
United Kingdom 044 437,850 
Denmark 045 865,850 
Sweden 046 437,850 
Norway 047 865,850 
Germany 049 437,850 
English (International) 061 437,850 
Portugal 351 860,850 
Finland 358 437,850 
Arabic countries 785 864,850 
Israel 972 862,850 


The United States code page is the default. 


Code page switching is not supported for Arabic countries (785) or Israel 
(972). 


The keyboard map files are as follows: 


Country or Language Keyboard Keyboard Map 
Model File 

United States AA stdus.key 
United Kingdom AA stduk.key 
Canadian AC stdca. key 
Danish AD st2dk.key 
Finnish AF stdfi.key 
German AG stdde.key 
Italian Al stdit.key 
Swiss French AK stdsfikey 
Swiss German AL stdsd.key 
Swedish AM stdse.key 
Norwegian AN st2no.key 
French AP stdfr.key 
Spanish AS stdes.key 
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Notes: 
+ Theconfig.sys file created by decselec on the target drive contains: 


country=yyy codepage path\country.sys 
¢ Theautoexec.bat file created by decselec on the target drive contains: 


path \;path 

keybrd 

deckeyb pathname 
echo off 

cls 

date 

time 

ver 


Examples: 


Suppose you want to create a new MS-DOS diskette that includes the coun- 
try-specific information and keyboard layout for Germany. With your source 
diskette in drive B and your target diskette in drive A, type: 


decselec b: a: 049 stdde.key 


MS-DOS displays a message warning you that it will erase all data on the 
target disk. 


Ifyou continue, MS-DOS prompts you to insert a new diskette in drive A. 
After it formats the diskette, MS-DOS copies files from the source diskette in 
drive B to the target diskette in drive A. 
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This is anew command. 

Purpose: 

Optimizes file storage on the specified disk. 
Syntax: 

diskopt 

Comments: 


Diskopt rearranges a disk’s file sectors into a contiguous (consecutive) for- 
mat. 


Always make a copy of a disk before optimizing it. If diskopt is interrupted 
during operation, the entire contents of the disk might be lost. 


Caution: Do not use diskopt on any disk that contains copy-protected pro- 
grams. 


To use diskopt, type the following command, and press ENTER. 
diskopt 

The screen displays the following prompt: 
Enter drive to optimize: 


Respond by pressing the letter of the drive that contains the disk to optimize. 


Diskopt analyzes each file on the indicated diskette or hard disk to determine 
whether the file’s sectors are consecutive. If they are not, it rearranges the 
sectors to make them consecutive. 


When a file on a disk is fragmented, reading or writing to that file requires 
extra drive head movement and reduces the speed at which the drive can 
access data. Diskopt reduces disk access time to a minimum. 
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Diskopt 
Notes: 


¢ Donotinterruptdiskopt by resetting or turning off your computer. Doing 
SO might make the entire contents of the disk useless. 


e Thedisk must contain at least one sector of free space before you can use 
diskopt successfully. 


Examples: 


This command executes diskopt. A promptasks you for the name of the drive 
that contains the disk to optimize. 


diskopt 
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This is an enhanced command. Use the following information instead of the 
information in the Microsoft MS-DOS User’s Reference. 

Purpose: 


Prepares MS-DOS for printing video graphics on a graphics printer. For 
example, to print MS- Windows screens or any application that has graphic 
video images, use the graphics command. 


Syntax: 
graphics [printer type}|/b]{/r] 
where printer type is one of the following: 


STD LNO3STD 
LASO LA210DEC 
LA75 LA210STD 
LA75STD LJ250DEC 
LA7S5DEC COLOR4 
LNO3 COLORS8 
LNO3DEC 

Comments: 


The LA75 printer is equivalent to an LA75STD. LNO3 refers to an LNO3 Plus 
printer. LNO3STD and LNO3DECare reserved for an LNO3 Plus printer with 
the LNO3 Plus ISO/PC cartridge. 


The graphics command accepts the following switches: 


Switch Purpose 
/b Prints the background color. This switch is valid only for color 


printers (printer types LJ2SODEC, COLOR4, and COLOR§8). 
The default is to not print the background. 


ir Specifies reverse, which prints exact graphic video images. If 
the screen has black video images with a white background, the 
printer produces black images with a white background. The 
default is to print black as white and white as black. 
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Assume you are using a color printer with the /b switch disabled and the /r 
switch enabled. The /r switch causes white to print as white and black to print 
as black. If the foreground (text and graphics) is white, and you press 
SHIFT + PRINT SCRN, a blank page is printed. This occurs because you did not 
specify the /b switch. Therefore, if you use /r with a white foreground, 
remember to use/b also. 


Notes: 


Do not load graphics from MS-Windows. 


Once you load graphics, you can print the current graphic video screen 
from MS-Windows by pressing SHIFT+PRINT SCRN. To change printer 
types and set the reverse or background switch, you must rerun the 
graphics command. 


To obtain high-quality prints, the graphics command causes printers in 
high-resolution video mode to print the upper-right corner of the screen 
on the upper-left corner of the paper (landscape mode). 


There are two ways to set the printer type: 


If you used the decmode command to set the printer, type the 
graphics command without the parameter or the switch. The graph- 
ics command reads the printer setting in memory. 


If you have not used the decmode command to set the printer, 
type the graphics command with the appropriate printer type and 
Switch. 


The graphics program stops if there is: 
No paper in the printer. 
An input/output (I/O) error during the print operation. 


A timeout. If a timeout occurs while the printer is in graphics 
mode, the printer remains in graphics mode. To reset an LA5O, 
LA75DEC, LA210DEC, LJ250DEC, LN03Plus, or LNO3DEC printer 
type, turn off the printer or complete the graphic printout. 
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Examples: 


To display the graphics help message, if you have not set the printer type 
using the decmode command, type: 


graphics 
To set the printer type to LA75 using the decmode command and then load 
graphics, type the following commands: 
decmode prn:1la75 
graphics 
The screen displays a message confirming the printer type and the print 
settings. 
To change the printer from an LA75 printer to an LNO3Plus printer, type: 
graphics 1n03 


To change the printer to an LNO3Plus and set the reverse switch, type: 
graphics 1n03 /r 
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This is anew command. 


Purpose: 

Enables you to use the Digital Gold ROM BIOS keyboard features present on 
the Digital LK250 keyboard. 

Syntax: 

keybrd 

Comments: 

You must run the keybrd command before you can use: 

e Thedeckeyb command 

¢ The keyboard functions of the decmode command 

e Any programs that require extended keyboard ROM BIOS functions 
Notes: 

e Donotuse thekeybrd command from MS-Windows. 


¢ ‘Youcan include the keybrd command in the autoexec.bat file if it is not 
already there. Thus, at system startup, the extended ROM BIOS functions 


are always available. 

¢ The decselec command automatically adds the keybrd command to your 
autoexec.bat file. 

Examples: 

To use the extended ROM BIOS functions, type: 
keybrd 
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This is a new command. 


Purpose: 


Changes the format ofa file to make the contents meaningless to anyone who 
does not know the encryption key (zero to eight characters that rerypt uses to 
alter the file format). 


Syntax: 
rerypt pathname! [ pathname2] 


where: 

pathname] is the pathname of the file to encrypt. 

pathnamez2 is the pathname of the file to receive the encrypted file. If you 
omit pathname2, rerypt uses the standard output device, the computer’s 
display. 

Comments: 

When you execute rerypt, a prompt asks you to: 


Enter encryption key : 


Type zero to eight characters that rerypt can use as the key in the encryption 
algorithm. The characters do not appear on the screen as you type them. 


Rcrypt now prompts: 
Re-enter encryption key for verification : 


Retype the encryption key exactly as you did the first time. Retyping helps 
ensure that you type the encryption key correctly so that you can later restore 
the file. 


You can cause rerypt to encrypt keyboard input by using a command such as 
this: 
rerypt con text.doc 


Here, rerypt encrypts keyboard input to a file named text.doc. To terminate 
input, press F6+ENTER. 
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Notes: 


e ‘You decrypta file in the same manner in which you encrypt it. You must 
supply the same key that you used for encryption. 


e ‘Youcan encrypt both ASCII and non-ASCII files. 
Examples: 


The following command encrypts a file named open.doc (if open.doc is a 
Standard file) and stores it in a file named secret.doc. If open.doc is an 
encrypted file, this command decrypts it and stores it in its original configu- 
ration in a file named secret.doc. 


rerypt open.doc secret.doc 
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This is an enhanced command. Use the following information instead of the 
information in the Microsoft MS-DOS User’s Reference. 


Purpose: 


Restores and makes usable files that were backed up using the backup 


command. 


Syntax: 


restore drivel :[path1} drive2: [path2] [filename] [/a:date][/b:date] 
[/extime) [/L:aime]{/m][/n][/p][/s] 


where: 
drivel: 


path1 


drive2: 


path2 


filename 


Comments: 


Is the drive containing the backup source files. 


Specifies the directory containing the backup source files. Ifyou 
omitpath1, the restore command uses the default directory on 
drivel:. 


Specifies the target drive, the drive to which backup files must 
be restored. 


Specifies the target directory where the backup files must be 
restored. The directory must exist, unless you use the/s switch. 
Ifyou use the /s switch, a subdirectory will be created if it does 
not exist. 


Specifies the file(s) you want to restore. If you specify filename, 
you must specify path. 


You can restore files to local drives, network drives, virtual disks, and sub- 


directories. 
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The restore command accepts the following switches: 


Switch 


/a:date 


/b:date 


/estime 


/L:time 


/m 


Purpose 


Restores files modified on or after the specified date. The date 
format depends on the country code. See Appendix E in the 
Microsoft MS-DOS User’s Reference for specific date formats. 


Do not use the /a switch with /b or /n. 


Restore /a works correctly only when the target drive contains 
files with the same names as those you want to restore. This 
occurs because the restore command must compare the dates 
of the backup files to the dates of the files on the target disk. 


Restores files modified on or before the specified date. The date 
format depends on the country code. See Appendix E in the 
Microsoft MS-DOS User’s Reference for specific date formats. 


Do not use the /b switch with /a or /n. 


Restore /b works correctly only when the target drive contains 
files with the same names as those you want to restore. This 
occurs because the restore command must compare the dates 
of the backup files to the dates of the files on the target disk. 


Restores files modified at or earlier than the specified time. The 
time format is 24-hour time, and the time separators are country 
dependent. The time format depends on the country code. See 
Appendix E in the Microsoft MS-DOS User’s Reference for 
specific time formats. Do not use the /e switch with /L. 


Restores files modified at or later than the specified time. The 
time format is 24-hour time, and the time separators are country 
dependent. The time format depends on the country code. See 
Appendix E in the Microsoft MS-DOS User’s Reference for 
specific time formats. Do not use the /L switch with /e. 


Restores files modified or deleted since the last backup. 
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/n Restores files that no longer exist on the target disk. Do not use 
this switch with /a or /b. 

/p Prompts you for permission to restore read-only files or files 
that have changed since the last backup procedure. 

/s Restores subdirectories. If the target disk does not contain the 


subdirectories from which the files were backed up, the 
subdirectories are created and the files are restored. 


Youcan use the/s switch without specifying a path, if the target 
directory is below the working directory. 


If you want to restore files that were backed up using restore /a, restore /b, 
or restore /m, the target disk must contain files with the same names as those 
files you want to restore. This is necessary because the restore command 
must compare the dates of the files that have the same names. Otherwise, the 
files are automatically restored. 


Notes: 


e Ifyou back up the hidden system files using the backup command, the 
restore command does not restore them. 


¢ Therestore command restores files only to the directory where the files 
originated. For example, if you back up files from c: \dir1 \dir2, you can 
restore the files only to \dir]\dir2 on the target device. 

e Youcan restore files from one hard disk partition to another hard disk 
partition. 

e Ifyou back up files to more than one diskette, restore prompts you to 
insert the diskette you started the backup process with. Restore prompts 
you to insert each diskette in sequence. Ifyou insert the wrong diskette, 
an error message is displayed. 
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Examples: 


To restore all .asm files from the root directory of drive A to the root directory 
of drive C, type: 


restore a: c:\*.asm /s 


The screen displays a message prompting you to insert the first backup 
diskette. Insert the diskette and press ENTER. The screen displays the name of 
each file as it is restored. 


To restore all the files from network drive I to drive C, type: 
restore i: c: /s 
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This is anew command. 
Purpose: 


Lets you send commands to the print spooler (and get the status of the 
spooler), assuming the spooler. sys device driver exists in your config. sys file. 


Syntax: 

spooler [/printer] [/p] [/s] [/e] [/2] 

Comments: 

The spooler command accepts the following switches: 


Switch Purpose 
/printer Is the number of the printer you want to use, either 1 or 2. If 


you omit the number, the system uses 1. Notice that you must 
precede the number with a slash (/). You can install two spoolers 
ifyou have two printers connected. 


/p Pauses the spooler. Using the /p switch is similar to toggling 
the off-line switch on the printer. Using /p a second time turns 
off the pause. To prevent the computer from locking up, the 
pause goes off automatically when the printer buffer is full. 


/s Interrupts the spooler’s buffering so that your computer 
immediately stops printing data in the buffer. All printer data 
goes directly to the printer. This feature enables you to print data 
without waiting until the buffer is empty. Use/s again to restart 


the buffering. 

Ie Clears the spooler. Any data remaining in the buffer is not 
printed. 

/g Returns the status of the spooler (installed, pause on/off, 


buffering on/off, size of buffer, percentage of buffer full). 
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Spooler 


Notes: 


e Thespooler slows any programs that disable the spooler idle interrupt, 
such as programs written in BASIC. 


e Thespooler might slow the CPU clock slightly. 


¢ See “New/Enhanced Device Drivers” for information on installing the 
spooler.sys device driver. 


Examples: 

The following example starts spooling for printer 1: 
spooler 

The following example pauses print spooling for printer 2: 
spooler /2 /p 

The following example restarts print spooling for printer 2: 
spooler /2 /p 
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Xonxoff 


This is anew command. 


Purpose: 


Provides support for asynchronous ports that have communications devices 
and attached serial printers that use the xon/xoff protocol. 


Syntax: 

xonxoff 

Comments: 

Do not use this command from MS-Windows. 


You must execute the xonxoff command before you use the following 
decmode functions: 


e Setting the printer type 
¢ Setting bypass modem control signals for communications setup 


You should execute the xonxoff command before you run the decmode 
command because xonxoff resets some parameters set by the decmode com- 
mand. To ensure that the xonxoff command executes before you run the 
decmode command, include the xonxoff command in your autoexec.bat file. 


Note: You must run the xonxoff command to use Digital’s serial printers, 
such as the LA75 Companion Printer, the LN03 Plus Laser Printer, and the 
LJ250 Companion Color Printer. 


Before using the xon/xoff protocol, disable modem control signals using the 
decmode command. 


Examples: 
To provide support for devices and printers that use the xon/xoff protocol, 
e: 


xonxoff 
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The information in this section applies to Appendix C, “Installable Device 
Drivers,” in the Microsoft MS-DOS User’s Reference. 


The following table summarizes the new or enhanced MS-DOS device driv- 
ers: 


Device Driver Purpose 

ansi. sys Loads the ANSI character set to provide programmers 
with extended screen and keyboard features. 

decmouse.sys Enables a Digital mouse to emulate a Microsoft mouse. 

demm.sys Enables application programs to access memory be- 
yond the traditional 640K memory boundary on 80386- 
based computers. 

spooler. sys Lets you continue processing data with your computer 
while using your printer. 

vdisk. sys Lets you establish a simulated (virtual) disk drive in 
RAM. 


The new and enhanced device drivers are described in detail on the following 
pages. For more information about the device configuration command, which 
is used to install these device drivers, see Appendix B, “How to Configure 
Your System,” in the Microsoft MS-DOS User's Reference. 
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Ansi.sys 


See Appendix C of the Microsoft MS-DOS User’s Reference for a detailed 
description ofansi.sys. Note that the list of graphics functions in Appendix C 
should not include function 6 (Rapid blink on). 


New/Enhanced Device Drivers 


Decmouse.sys 


Decmouse.sys is an installable device driver that allows a Digital mouse used 
with a DEPCA board to emulate a Microsoft mouse. This ability enables you 
torun many applications that assume a Microsoft mouse is present. 


To install decmouse.sys, insert the following command line in your config. sys 
file: 
device=decmouse.sys 


Load decmouse.com as you need it, before running the application with which 
you want to use the Digital mouse. To loaddecmouse.com, type decmouse 
at the MS-DOS system prompt. 


Note: You cannot use the decmouse command from MS- Windows. 
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Demm.sys 


Demm.sys is an expanded memory manager for the DECstation 316, DEC- 
Station 320, and other 80386-based computers with extended memory. 
Demm.sys enables application programs to access memory beyond the mem- 
ory limit recognized by MS-DOS. Your application must support the 
Lotus/Intel/Microsoft (LIM) Expanded Memory Specification (EMS) Ver- 
sion 4.0 or earlier to use demm.sys expanded memory. 


Note: Demm.sys is not designed to run over a network. 


Types of Memory 


Conventional memory is the memory used to fill PC/AT system memory. The 
maximum conventional memory recognized by MS-DOS is 640K. AT slots 
(expansion slots) are 16-bit slots on the computer’s main logic board. AT slots 
are two connector slots that are approximately 5.5 inches long. 


Expanded memory provides additional memory with the first megabyte of 
address space for use by applications. It is memory that is not allocated as part 
of the normal PC/AT linear memory. Expanded memory is swapped in and 
out of the PC/AT address space so that it can be recognized by MS-DOS. 
Device drivers such as demm.sys are required to use expanded memory. 


Extended memory provides additional memory beyond the 1M that the 80386 
processor can address. Extended memory is at addresses of 1M or greater on 
the PC/AT and is part of the linear PC/AT memory. 


System Requirements 


Demm.sys requires a DECstation 80386-based personal computer and MS- 
DOS Version 3.3 or later. 


The amount of conventional memory and extended memory used by 
demm.sys depends on the amount of memory to be managed. The standard 
DECstation 316 is equipped with 1M (1024K) of RAM on the main board. Of 
this RAM, the operating system and applications use 640K. The system also 
reserves an additional 80K. This leaves 304K of memory available to spe- 
cially written software such as demm.sys. 


Demm.sys is implemented as a device driver to allow other device drivers to 
use an expanded memory manager. Other device drivers include the RAM 
disk driver (vdisk. sys) and the printer spooler program (spooler.sys), as well as 
other application software programs. 


New/Enhanced Device Drivers 


Demm.sys 


Installation 


To install demm.sys, modify your config.sys file by entering the following 
line: 


device=demm.sys|/s] pxxxx] [Iy ][Mz] 


where: 
/s enables the software to access shadow RAM. 


xxxxx represents the actual size of expanded memory (in kilobytes) to be 
emulated. Use a value in the range 304 to 8192 (ifyou are using the /s option) 
or 16-8192 (if you are not using /s). The system rounds xxxx down to the 
nearest multiple of 16. The default value is 304K (with /s) or 1024 (without 
/S). 


y (ly) represents the number of the I/O port addresses emulated bydemm.sys. 

Ifyou have one or more hardware boards in your system that also use the port 
addresses accessed by demm.sys, use the following chart to select port ad- 
dresses that do not conflict with these boards. If you do not specify y, the 
default is 5. 


The /a switch for vdisk and spooler lets you use an expanded memory that 
meets the Lotus/Intel/Microsoft Expanded Memory Specification if the Ex- 
panded Memory Manager software has been installed. 


y Value Port Addresses Used (Hex) 

0 208 4208 8208 C208 
1 218 4218 8218 C218 
5 258 4258 8258 C258 
6 268 8268 8268 C268 
10 2A8 42A8 82A8 C2A8 
11 2B8 42B8 82B8 C2B8 
14 2E8 42E8 82E8 C2E8 


47 


DECstation Enhancements 


Demm.sys 


z (Mz) represents the frame base address for demm.sys to use for LIM page 
mapping. The default is 3. 


z Value Frame Address (Hex) 
0 C400 
1 C800 
2 ccoo 
3 D000 
4 D400 
5 D800 
6 DC00 
7 E000 
Examples: 


Insert the following lines in your config.sys file to initialize the Digital 
expanded memory manager and use your system’s 304K bytes of free mem- 
ory to run vdisk and spooler. These lines give vdisk 272K of memory and 
spooler 32K of memory. 

device=demm.sys /S 304 I5 M3 

device=vdisk .sys 272 /A 

Gdevice=spooler.sys 32 /A 
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Spooler.sys 


Spooler.sys is a loadable driver that buffers data to the printer by temporarily 
placing the data in memory. Spooler spools the data to the printer whenever 
the printer is available. In this way, you can continue to use your computer to 
process data while printing other data. 


The device command that you need to place in config. sys to install the printer 
buffer driver is: 


device=spooler.sys [ printer]|size]|{/e] 
or 
device=spooler.sys | printer][size}{/a] 


where: 

printer is the number of the printer you want to use. It can be either 1 or 2. If 
you omit the number, the system assumes you want to use Printer 1. Notice 
that you must precede the number with a slash (/). You can install two 
spoolers ifyou have two printers connected. 


size is the buffer size in kilobytes. If you omit size, the system uses 2K. 
Spooler.sys accepts the following switches: 


Switch Purpose 
le Lets you use extended memory (above one megabyte) as a 


virtual disk. Ifyou use this switch, you cannot use the /a switch. 


/a Lets you use an expanded memory board that meets the 
Lotus/Intel/Microsoft Expanded Memory Specification if the 
Expanded Memory Manager software has been installed. Ifyou 
use this switch, you cannot use the /e switch. 
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Vdisk.sys 


Vdisk.sys is an installable device driver that lets you use a portion of your 
computer’s memory as if it were a hard disk. This memory area is called a 
virtual disk or RAM disk. When you reset or turn off your computer, the 
information stored in virtual disks is lost. 


Note: Vdisk.sys performs the same function as the MS-DOS device driver 
ramdrive.sys. 


Virtual disks are much faster than hard disks because the information they 
contain is always loaded into memory. If your computer has extended mem- 
ory installed (starting at the 1M boundary), or if you have an expanded 
memory board that meets the Lotus/Intel/Microsoft Expanded Memory Spec- 
ification, you can use this expanded memory for one or more virtual disks. 
Otherwise, vdisk. sys places virtual disks in low memory. 


Note: Using vdisk.sys (including a device=vdisksys statement in your con- 
fig.sys file) increases the size of MS-DOS resident in memory. 


To install vdisk.sys, include a command line of the following form in your 
config. sys file: 


device=vdisk.sys [disksize] [sectorsize] [entries] [/e] 
or 
device=vdisk.sys [disksize] [sectorsize] [entries] [/a] 


The vdisk.sys device driver accepts the following options: 


Option Function 
disksize Specifies the disk size in kilobytes. The default size is 64K; the 
minimum size is 2K. 


sectorsize Specifies the sector size in bytes. The default size is 128 bytes. 
Allowed values are 128, 256, and 512 bytes. 
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New/Enhanced Device Drivers 


Vdisk.sys 


Specifies the number of root directory entries. The default value 
is 64, the minimum value is 2, and the maximum value is 512. 


Vdisk.sys adjusts the value of entries to the nearest sector 
boundary. 


Lets you use extended memory (above 1M) as a virtual disk. If 
you use this switch, you cannot use the /a switch. 


Lets you use an expanded memory board that meets the 
Lotus/Intel/Microsoft Expanded Memory Specification if the 
Expanded Memory Manager software has been installed. Ifyou 
use this switch, you cannot use the /e switch. 
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This section provides additional information about the various commands and 
concepts described in the Microsoft MS-DOS User’s Guide and the Microsoft 
MS-DOS User’s Reference. See the manuals themselves for more informa- 
tion. Chapter names and numbers are included for your convenience. 


Write Protecting 3.5-Inch Diskettes 


User’s Guide, Chapter 2, “Learning About Disks, Files, and Directories” 


The information about write protecting 3.5-inch diskettes is incorrect. A 
3.5-inch diskette is write protected when the built-in tab does not cover the 
rectangular write-protection hole. 


How to Rename a Directory 


User's Reference, Chapter 1, “More About Files and Directories” 
This chapter indicates that you can rename a directory that has no subdirector- 
ies. You cannot do this directly. To rename a directory, create an identical 


directory structure under a new name. Then, copy any files in the original 
directory into the new one, and remove the original directory. 
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MS-DOS Commands 
User’s Reference, Chapter 3, “MS-DOS Commands” 


Append 


The list of system calls given with the append command is incomplete. The 
complete list is: 


Code Function 


OFH Open File (FCB) 

11H Search First Entry (FCB) (with/x option only) 

12H Search Next Entry (FCB) (with /x option only) 

23H Get File Size (FCB) 

3DH Open File (Handle) 

4BH Exec (with /x option only) 

4EH Find First Matching File (Handle) (with/x option only) 
4FH Find Next Matching File (Handle) (with/x option only) 


Chcp 


The chep command displays or changes the current code page for the com- 
mand processor, command.com. Before using chep, you must use nlsfunc to 
load the country-specific information and mode to prepare code pages for the 
devices. 


Del 


You can delete all the files in a directory by specifying a path, instead of a 
pathname, with the del command. For example, typedel \mystuff ENTER 
to erase all the files in the \mystuff directory. The screen displays a prompt 
asking whether you are sure you want to erase all the files. 
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Diskcomp 

This command compares the contents of two diskettes. It cannot compare 
hard disks. 

Format 


The following syntaxes clarify which switches are available, depending on 
the type of disk you are formatting: 


format drive: [/1]{/4][/8][/b] [/v]|[/s]5.25-inch diskette drives 
format drive: [/nzxx][/tyy ]{/v][/s]3.5-inch diskette drives 
format drive: [/v][/s]hard disk drives 


Graftabl 
The multilingual code page (850) is not available. 


Keyb 
A keyboard program is available for French-speaking Canada as well as the 
other countries listed in the Microsoft MS-DOS User’s Reference. Use the 
keyb cf command to load this program. 
Mode (Asynchronous Communications) 
The 19200 baud rate listed in the Microsoft MS-DOS User's Reference cannot 
be used on the DECstation computers. 
More 
The following syntaxes clarify how to use the more command: 

more <[drive:|pathname 

or 

source , more 


where source is a command producing output to the screen. 


Print 


Valid values for /s:timeslice range from 1 to 255. The default is 8 time slices. 
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Select 
The select command can be used to install MS-DOS (with country-specific 
information and keyboard layout) on hard disks as well as diskettes. Use 
select with keyboards other than the Digital LK250. Use decselec with the 
LK250. 
Sort 
The following syntaxes clarify how to use the sort command: 

sort [/r] [4n] [<[drive:|pathname!][>|drive:|pathname2] 

or 

[source |] sort [/r] [/+7] 


where source is acommand producing output to thescreen. 


Subst 

The subst command lets you simplify references to a directory. Once you use 
subst to associate a directory name with a drive letter, you can use the drive 
letter instead of the path when referring to that directory. 

Sys 

The disk to which you are transferring the system either must be empty or 
must have been formatted with the/b switch. 

Tree 


Typing tree ENTER displays the names ofall directories and subdirectories 
on the current disk, not of all directories and subdirectories on the computer. 


Echo 


User’s Reference, Chapter 4, “Batch Processing” 


The purpose listed for the echo command is incomplete. Echo turns the batch 
echo feature on and off, displays the current setting of echo, or displays a 
specified message. Echo followed by a period (echo .) displays a blank line. 
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Config.sys 
User’s Reference, Appendix B, “How to Configure Your System” 


In the sample config. sys file, c:\bin (not a:\bin) tells the command processor 
where to look for command.com if it needs to reread the disk. 


Preparing Your DECstation Computer’s 
Hard Disk 


User’s Reference, Appendix D, “Configuring Your Hard Disk” 
This section includes information that is specific to DECstation computers. 


Before any hard disk can store information, it must be hard formatted, 
partitioned, and then soft formatted. 


Caution: Never use the Utilities diskette to hard format the SCSI hard disk in 
your DECstation computer. This drive either was hard formatted at the fac- 
tory or has its own hard format utility. The utility on your Utilities diskette is 
for optional ST-506 hard disks only. 


1. Write protect your MS-DOS diskettes. 
2. Startupyour computer with the MS-DOS Startup diskette in drive A. 


3. Use the MS-DOS fdisk command to partition the hard disk. Fdisk is 
described in Appendix D in the Microsoft MS-DOS User's Reference. 


4. Usethe MS-DOS format command to soft format the hard disk. Format 
is described in the Microsoft MS-DOS User’s Guide and Microsoft MS- 
DOS User’s Reference. 
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Switching Between Code Pages 
User’s Reference, Appendix E, “How to Use Code Pages” 


Replace the entire example in the manual with: 


If you work in an environment that uses more than one language, you might 
need to switch between code pages. For example, suppose you work for an 
international company with offices in New York, London, Stockholm, and 
Oslo. You might need to use two or three different code pages to read or work 
from the correspondence you receive from your other offices. 


To illustrate how to switch code pages for your system and your devices, 
suppose that you want to change to Nordic code page 865 to work with some 
information you receive from the Oslo office. Follow these steps: 


1. Type the nlsfunc command. You need to type this command only once 
in order to load the country-specific information from thecountry.sys file. 


2. Prepare the code page for each device you intend to use. For example, 
type the following command to prepare code page 865 for the parallel 
printer connected to LPT2: 


mode lpt2 codepage prepare=((865) 4201.CPI) 
MS-DOS then displays the following message to let you know the 
code page is prepared for your device: 

MODE Prepare Codepage function completed 


3. To prepare code page 865 for your console screen device (CON), type: 
mode con codepage prepare=((865) ega.CPI) 


4. Change the code page for the system and all prepared devices by typing: 
chep 865 


The display on your screen might flicker slightly as MS-DOS loads 
a new code for that device. 


5. If for some reason you want to load a different code page for a single 
prepared device, use the select keyword with the mode command. For 
example, to load code page 850 for your printer, type: 


mode lpt2 codepage select=850 
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MS-DOS then displays the following message to let you know the 
code page is prepared for your device: 


MODE Select Codepage function completed 


Note: If you want to use these commands on a regular basis, you can in- 
Clude these command lines in your autoexec.bat file. 


Messages 


User’s Reference, Appendix F, “MS-DOS Message Directory” 


The following messages are an addition to the alphabetical list in Appendix F. 
Each message is followed by an explanation of the problem and the action 
necessary to correct it. The utilities or programs that generated the message 
are also included, in parentheses. 


Another version was already in memory. The new 
version has been loaded on top of the old one. 
( DECMOUSE ) 


Explanation: The mouse driver was installed over an older version 
of the mouse driver (decmouse.sys). 


Action: Always use the latest version of the mouse driver. 
APPEND/ASSIGN conflict (APPEND) (ASSIGN) 


Explanation: The assign command was used followed by the ap- 
pend command. 


Action: Both assign and append are terminate-and-stay-resident pro- 
grams. If you use these commands together, you must use append 
before assign. Restart your DECstation computer. You might need 
to edit your autoexec.bat file if it contains these commands. 


APPEND/TOPVIEW conflict (APPEND) 


Explanation: The topview command was used followed by the ap- 
pend command. 


Action: If you use these commands together, you must use append 
before topview. 
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Cannot execute FORMAT (BACKUP) 


Explanation: The target diskette must be formatted, and backup 
could not run the format command. 


Action: Be sure you set the path to include the directory containing 
the format command. 


Cannot FORMAT nonremovable drive x: (BACKUP) 


Explanation: You tried to back up a file to an unformatted hard 
disk partition. 


Action: Format the hard disk partition before attempting to back up 
files to it. 


Disk full error writing to BACKUP Logfile 
(BACKUP ) 


Explanation: The device to which backup is writing the log file is 
full. Logging terminates, but the backup procedure continues. 


Action: If you want a log file, delete some files to free more 
memoty. 


Driver already installed (DECMOUSE) 


Explanation: You tried to install the mouse driver (decmouse.sys), 
but it is already installed. 


Action: Install decmouse.sys only once. 
Error opening logfile (BACKUP) 


Explanation: The backup command could not open the log file. 
You specified an invalid path, or the log file is set to read-only. 


Action: Specify a valid path to the log file. If a read-only version 
of the log file already exists, use the attrib command to clear the 
read-only attribute. 
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Error reading file ‘filename’ (DECKEYB) 
Explanation: The program cannot read the file you specified. 


Action: Re-enter the command. If this message is displayed again, 
restore the file from your backup diskette. 


File creation error (RESTORE) 
Explanation: One of the following occurred: 
¢ There is no more space. 
e ‘You reached the maximum number of directories. 
¢ The file is a read-only file and cannot be replaced. 
Action: Attempt one of the following: 
e Runthechkdsk command to see how much space is left on the disk. 
* Deletesome files. 
e Deletesome directories. 


¢ Use the attrib command to determine whether the file is read-only. 
If it is, use the attrib command to change it. 


File not found ‘filename’ (DECKEYB) 


Explanation: The operating system could not find the file you spec- 
ified. 
Action: Be sure the name is correct, the file exists in the directory 
on the disk, and the path is valid. 

Fixed back-up device x: is full (BACKUP) 


Explanation: The destination disk has no room to receive backup 
files. 


Action: Use another disk as the destination. 
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Incorrect DOS version 


Explanation: You tried to use an incorrect version of the operating 
system on your DECstation computer. 


Action: Use MS-DOS Version 3.2 or 3.3. Contact your system ad- 
ministrator to obtain the correct version of MS-DOS. 


Insufficient memory (BACKUP) (RESTORE) 


Explanation: There was not enough memory to run the specified 
command. You might have too many terminate-and-stay-resident pro- 
grams, or your directory structure might be too complex. 


Action: Because certain MS-DOS commands and programs are ter- 
minate-and-stay-resident, restarting your DECstation computer might 
free enough memory to run the desired program. If not, you must 
edit the config.sys file, remove some of these commands and pro- 
grams, and then restart the computer. Also, if you installed any 
device drivers, delete them from config.sys. 


Insufficient memory to complete this listing 
(BACKLIST) 


Explanation: There was not enough memory to run the backlist 
command. You might have too many terminate-and-stay-resident pro- 
grams, or your directory structure might be too complex. 


Action: Because certain MS-DOS commands and programs are ter- 
minate-and-stay-resident, restarting your DECstation computer might 
free enough memory to run the desired program. If not, you must 
edit the config.sys file, remove some of these commands and pro- 
grams, and then restart the computer. Also, if you installed any 
device drivers, delete them from config.sys. 


Invalid command line parameters (DECMODE) 
Explanation: You entered invalid parameters on the command line. 


Action: Check for misspellings and missing punctuation. Re-enter 
the command. 
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Invalid date (BACKUP) 
Explanation: You specified an invalid date. 


Action: Check for misspellings and typing errors. Re-enter the com- 
mand. 


Invalid drive specification (BACKUP) (RESTORE) 


Explanation: You specified a drive that does not exist on your 
system. 


Action: Specify a valid drive. 
Invalid input line (GRAPHICS) 


Expianation: You specified invalid information on the command 
line. 


Action: Re-enter the graphics command, specifying a valid printer 
type. 
Invalid number of parameters (BACKUP) (RESTORE) 


Explanation: You specified either too many or too few parameters 
on the command line. 


Action: Re-enter the command, specifying the correct number of 
parameters. 


Invalid parameter 
Explanation: One of the parameters you specified is invalid. 


Action: Be sure you entered the parameters correctly. Re-enter the 
command. 


Invalid path (BACKUP) (RESTORE) 
Explanation: You specified a path that does not exist. 


Action: Be sure you entered the pathname correctly. To see the 
current pathnames, type: 


path ENTER 
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Invalid time (BACKUP) 


Explanation: You specified an invalid time. 


Action: Check for misspellings and typing errors. Re-enter the com- 
mand. 


KEYBRD already loaded (KEYBRD) 
Explanation: Keybrd has already been loaded. 
Action: Do not run keybrd more than once. 
Last back-up diskette not inserted (BACKUP) 


Explanation: You specified /a but did not insert the last 
diskette. 


Action: Insert the last diskette. 
Last file not backed up (BACKUP) 


Explanation: The last file was not backed up for any of 
the following reasons: 


¢ ‘You pressed CTRL+C. 

¢ You need to insert a new diskette. 

¢ There is no more space on the hard disk. 
Action: Try one of the following: 

¢ Backup the displayed file. 

¢ Insert a new diskette. 


e Delete some files from the hard disk and re-enter the backup com- 
mand. 


Mouse port not found or not working! (DECMOUSE) 


Explanation: There is no DEPCA board present, or the DEPCA 
ROM location address conflicts with another option board or 
adapter board in your system. 


Action: Select another DEPCA ROM address location. Or, if no 
DEPCA board is present, insert a DEPCA board into your com- 
puter, restart the system, and install the mouse driver, decmouse.sys. 
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No APPEND (APPEND) 


Explanation: Append has been loaded, but no path has been ap- 
pended yet. 


Action: Assign a path to the append command. For more informa- 
tion, see the append command in the Microsoft MS-DOS User’s 
Reference. 


No files were found to back up (BACKUP) 
Explanation: No files were found on the specified source disk. 


Action: Be sure you entered the source file specification correctly. 
Re-enter the backup command, and specify the correct file(s). 


No files were found to restore (RESTORE) 
Explanation: No files were found on the source disk to restore. 


Action: Be sure you entered the file specification correctly. Re-enter 
the restore command, and specify the correct file(s). Also, be sure 
you are in the correct directory for restoring the files. You must be 
in the original directory to restore the files. 


No source drive specified (BACKUP) 
Explanation: You did not specify a source drive. 


Action: Re-enter the command and specify a source drive letter 
followed by a colon. 


No switches specified for sort request 
(BACKLIST) 


Explanation: You specified /s but did not include any sort options. 
Action: Re-enter the command and specify sort options for /s. 

No target drive specified (BACKUP) 
Explanation: You did not specify a target drive. 


Action: Re-enter the command and specify a target drive letter fol- 
lowed by a colon. 


64 


MS-DOS Notes 


Not a keyboard map file (DECKEYB) 
Explanation: You specified a file that was not a keyboard map file. 


Action: Re-enter the deckeyb command, and specify a valid key- 
board map file. If it was a valid keyboard map, restore the original 
file from your distribution diskette. 


Not able to back up file (BACKUP) 


Explanation: The backup command could not back up this file 
because of a read/write error or file open error. 


Action: Restart your computer, and re-enter the backup command. 
If this message is displayed again, be sure the file exists. If it does 
exist, save the file using the copy command, or increase the value 
of the files command in the config.sys file. 


Not able to restore file (RESTORE) 


Explanation: No files were found to restore. 


Action: Be sure you entered the file specification correctly. Re-enter 
the restore command, and specify the correct file(s). 


Path too long, unable to back up directory: 
path (BACKUP) 


Explanation: You entered a pathname that exceeds the MS-DOS 
limit of 64 characters. 


Action: You should move files you want to back up closer to the 
root directory, to shorten the pathnames. 


Please run the KEYBRD program (DECKEYB) 
( DECMODE ) 


Explanation: You ran the deckeyb program or the decmode pro- 
gram before you loaded keybrd. 


Action: Run the keybrd program before you run deckeyb or 
decmode. 
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Please run the XONXOFF program before 
redirecting output. (DECMODE) 


Explanation: You tried to redirect LPT# without first running the 
xonxoff program. 


Action: Run xonxoff before you redirect LPT#. 


Print quality HIGH is not supported on STD type 
printers (DECMODE) 


Explanation: You specified the h parameter for an unqualified 
printer. The h parameter is valid only for LA50-type printers. 


Action: Specify the h parameter only with LA50-type printers, such 
as the LA50, LA7SDEC, and LA210DEC. Re-enter your current 
command line without the h parameter. 


Printer type UNKNOWN (DECMODE) (GRAPHICS) 


Explanation: You did not specify a printer type using the decmode 
command, and you did not supply the printer type when you en- 
tered the graphics command. 


Action: Run decmode and specify your printer, or specify a printer 
type on the graphics command line. To see the valid printer types, 
enter: 


graphics ENTER 


Printing the background is for color printers 
only (GRAPHICS) 


Explanation: You used /b on the graphics command line with a 
non-color printer. 


Action: Use /b only with a color printer. 


Required drive letter not supplied (BACKLIST) 
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Explanation: You did not specify the drive that the backlist com- 
mand was to search for backup information. 


Action: Run backlist, and specify a valid drive letter. 
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Restore file sequence error (RESTORE) 
Explanation: You tried to restore a file out of order. 
Action: Insert the appropriate diskette into the diskette drive. 
SHARE already installed (SHARE) 
Explanation: You tried to load and execute share more than once. 
Action: Run share only once. 


Source and target drives are the same 
(BACKUP) (RESTORE) 


Explanation: You tried to back up files to the same disk from 
which you copied them. 


Action: Be sure the source and target drive specifications are differ- 
ent. 


Source does not contain back-up files (RESTORE) 
Explanation: The source disk had no backup files on it. 


Action: Be sure you entered the information on the command line 
correctly. If you did, be sure the backup files are in the specified 
directory. If they are not, re-enter the command and specify the 
correct directory. 


Target cannot be used for back-up (BACKUP) 
Explanation: One of the following occurred: 
¢ Thebackup command cannot access the disk. 
¢ The diskette is bad or unformatted. 
¢ Thereare hardware problems. 


e You specified /a, but there were no backup-created files found to 
which more files could be added. 


Action: Reformat the diskette using the format command. Re-enter 
the backup command. If this message is displayed again, try a new 
diskette. 


If there are hardware problems, call your authorized service repre- 
sentative. 
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Target is full (RESTORE) 
Explanation: The target disk had no room to receive restored files. 
Action: Use another disk as the target disk. 

Target not a directory (BACKUP) 


Explanation: You specified an invalid target for the backup proce- 
dure to nonremovable media. 


Action: You must specify a valid directory as the target for the 
backup procedure. 


Target path invalid (BACKUP) 


Explanation: You specified an invalid path to the destination direc- 
tory. 


Action: Check for misspellings. Specify a valid path to the destina- 
tion directory. 


The 96-column mode is not supported for the 
STD type printer (DECMODE) 


Explanation: You tried to use 96-column mode with an STD-type 
printer. This mode is valid only for LASO-type printers. 


Action: Re-enter the command without specifying 96-column mode. 
The last file was not restored (RESTORE) 

Explanation: One of the following occurred: 

e You pressed CTRL+C. 

e — Itis time to switch diskettes. 

e There is no more space on the hard disk. 

Action: Try one of the following: 

¢ Re-enter therestore command. 

e  [nserta newdiskette. 


e Deletesome files from the hard disk and re-enter the command. 
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The mouse is not responding (DECMOUSE) 


Explanation: There is a DEPCA Ethernet adapter, but the mouse 
does not respond. 


Action: Check the mouse installation and then rerun the mouse 
driver. 


The path entry is too long (DECKEYB) 
Explanation: You specified a pathname of more than 64 characters. 
Action: Enter a pathname of 64 or fewer characters. 


The path is not set and the file was not found 
in the current directory or root directory: 
‘filename’ (DECKEYB) 


Explanation: You have not set the path, or the file was not found. 
Action: Set the path and be sure you specified a valid filename. 


The PATH= string was not found in the 
environment (DECKEYB) 


Explanation: Your environment space is corrupt. 
Action: Restart the computer. 


The specified file is invalid or does not 
exist: ‘filename’ (DECKEYB) 


Explanation: One of the following occurred: 

¢ There is an illegal character in the filename. 
¢ The key file is not in the proper format. 
Action: Try one of the following: 

¢ Check the filename for illegal characters. 


e  Besure the key file is in the proper format. 
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Too many parameters on the command line 
(BACKLIST) 


Explanation: You specified too many options with the backlist com- 
mand. 


Action: Run backlist with the correct number of options. 
WARNING: Diskette is out of sequence (RESTORE) 


Explanation: The diskette you entered is not the next diskette in the 
sequence. 


Action: Insert the appropriate diskette into the drive. 
XONXOFF already loaded (XONXOFF) 
Explanation: Xonxoff has already been loaded. 


Action: Load xonxoff only once. 
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Loading GW-BASIC 


To load GW-BASIC, do not type gwbasic as instructed in the Microsoft 
GW-BASIC User’s Guide. Instead, type basic ENTER at the MS-DOS 
system prompt. Once you enter GW-BASIC, the GW-BASIC prompt, Ok, 
replaces the MS-DOS prompt. 


Loading BASIC with BASICA 


For compatibility, some computers require that you use the BASICA program 
to load GW-BASIC. To use BASICA, typebasica ENTER. 


The computer loads basica.com, which in turn loads GW-BASIC. 


BASICA provides the following advantages: 


e BASICA loads BASIC ata different memory location. This lets you run 
some BASIC programs that use memory locations normally reserved for 
BASIC’s operations. 


e  Youcan gain space on your program or system diskette because you can 
store the basic. exe file on a separate diskette. 

The only limitations imposed by BASICA are: 

* The/i option switch is always on. 

e Thecommunications buffer size is limited to 40K bytes if the system has 
one RS232 card or 20K bytes if it has two. 


After you execute BASICA, it searches the current directory for the file 
basic.exe. If it finds basic.exe, basica.com loads it and passes control to it. 


If basica.com does not find basic.exe, it asks you to replace your program 
disk with a disk that contains the file. Place a diskette containing basic.exe in 
any drive, and press ENTER. The program searches all drives, beginning with 
the current drive, until it finds basic.exe or until you press CTRL+C. 


After finding basic.exe, BASICA asks you to re-insert your program diskette 
if you removed it. Put the program diskette back into the drive and press 
ENTER. BASICA transfers control back to BASIC. 
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Welcome 


Welcome to the MS-DOS operating system, version 3.3. If you are new at 
working with operating systems for personal computers, you will want to learn 
a few basics before you go on to learn about the advanced features of MS-DOS. 
This MS-DOS User's Guide was written to help you understand the 
fundamentals of using MS-DOS with your personal computer. 


Once you have read this MS-DOS User's Guide, or if you are already an 
advanced personal computer user, see the MS-DOS User's Reference, which 
presents the features of MS-DOS, and describes each MS-DOS command in 
detail. In addition, programmers may be interested in the MS-DOS 
Programmer's Reference, which introduces programmers to MS-DOS, and 
describes all the MS-DOS system calls. 
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Before You Begin 


Before you begin using this MS-DOS User's Guide, you should have 


e A 16-bit personal computer that runs MS-DOS and has at least 256K bytes 
of memory. 


e Two disk drives (either two floppy disk drives, or one hard disk drive and 
one floppy disk drive). 
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Notational Conventions 


Throughout this manual, the following conventions are used to distinguish 
elements of text: 


bold Used for commands, options, switches, and literal portions 
of syntax that must appear exactly as shown 

italic Used for filenames, variables, and placeholders that 
represent the type of text to be entered by the user 

monospace Used for sample command lines, program code and 


examples, and sample sessions 
SMALL CAPS Used for keys, key sequences, and acronyms 


How to Use This Guide 


This manual introduces you to the MS-DOS operating system and teaches you 
how to use several MS-DOS features. The manual is organized so that you can 
easily find what you need to know, as in the following list, which gives you a 
quick overview of the topics covered. 


Turn to To learn 
Chapter 1 About your keyboard 
Chapter 2 About disks and files 


Chapter 3 How to start MS-DOS 
How to quit MS-DOS 


Chapter 4 How to use MS-DOS commands 
How to print a file 


Chapter 5 How to run a program How to create a file 


Chapter 6 What the config.sys file does 
What the autoexec.bat file does 
How to modify these two files 


Terms About MS-DOS terminology 
To learn more about MS-DOS, refer to the MS-DOS User's Reference. 


1 Learning About MS-DOS 


In this chapter you will learn about 
e Important MS-DOS terms 
e Your personal computer’s keyboard 





1.2 MS-DOS User's Guide 


Terms You Should Know 


When you are introduced to a new or different idea, you must often learn a new 
set of words to understand the idea. The MS-DOS operating system is no 
exception. The following pages explain some terms you will need to know so 
that you can read and use this manual. If you are already familiar with MS- 
DOS, you may find the MS-DOS User's Reference more helpful. 


Program 


Programs, often called application programs, applications, or software, are 
series of instructions written in computer languages. These instructions are 
stored in files and tell your computer to perform a task. For example, a program 
might tell your computer to alphabetically sort a list of names. Spreadsheets 
and word processors are other examples of programs. 


File 


A file is a collection of related information, like the contents of a file folder in a 
desk drawer. File folders, for instance, might contain business letters, office 
memos, or monthly sales data. Files on your disks could also contain letters, 
memos, or data. For example, your MS-DOS master disk contains more than 
thirty files. Your other disks may contain files that you’ve created, or that 
came with the disk. 
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Filename 


Just as each folder in a file cabinet has a label, each file on a disk has a name. 
This name has two parts: a filename and an extension. A filename can be from 
one to eight characters in length, and can be typed in uppercase or lowercase 
letters. MS-DOS automatically converts filenames to uppercase letters. 


Filename extensions consist of a period followed by one, two, or three 
characters. Extensions are optional, but it’s a good idea to use them, since they 
are useful for describing the contents of a file to you and to MS-DOS. For 
instance, if you want to be able to quickly identify your report files, you can 
add the filename extension .rpt to each one. Here’s an example of a filename 
with this extension: 


progress.rpt 





filename filename extension 


When you look at the directory on your MS-DOS master disk, you will see 
many files with the extension .exe or .com. The extension .exe means 
executable, and .com means command. These extensions tell MS-DOS that the 
files are programs that can be run. Many files will have other kinds of 


1.4 MS-DOS User's Guide 


extensions, such as .doc and .txt, which might contain text. Another common 
program file extension is .bas for BASIC programs. Some application 
programs assign filename extensions automatically. For example, Microsoft 
Multiplan® assigns the extension .mp, and Lotus 1-2-3 assigns one of three 
extensions, for instance .wks for worksheet files. 


Directory 


A directory is a table of contents for a disk. It contains the names of your files, 
their sizes, and the dates they were last modified. 


Volume Label 


When you use a new disk, you can put a label on the outside of it to help you 
identify its contents. You can also give each of your disks an internal name, 
called a volume label. 


You can look at the volume label on a disk by displaying its directory. Some 
programs may look at the volume label to see if you are using the correct disk. 
So make sure that you label your disks. See Chapter 4, "Using Commands," for 
step-by-step instructions on how to create a volume label for a disk. 


Disk Drive 


To use the files or programs that are on a floppy disk, you must first insert the 
disk into a floppy disk drive. Floppy disk drives are commonly referred to as 
the A drive and the B drive. A hard disk drive, normally installed inside your 
computer, is usually referred to as the C drive. Check your computer manual to 
see which drive is A and which is B (or C). 





Floppy disk drive Hard disk drive 
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Drive Name 


A complete drive name consists of a drive letter and a colon. When using a 
command, you may need to type a drive name before your filename to tell MS- 
DOS where to find the disk that contains your file. For example, suppose you 
have a file named finances.doc on the disk in drive B. To tell MS-DOS where 
to find this file you would type the drive name before the filename: 


b:finances.doc 


drive name _— |filename with extension 
The Default Drive and the MS-DOS Prompt 


If you don’t specify a drive name when you type a filename, MS-DOS 
automatically searches for the file on the disk in the default drive. The default 
drive is where MS-DOS searches first when you type a command. To let you 
know that it is ready to receive a command, MS-DOS displays a symbol, called 
a prompt, that contains the default drive letter followed by a greater-than sign 
(>). Following the greater-than sign is the cursor, the blinking box or flashing 
underline that shows where the next character you type will appear. Here’s an 
example of a typical MS-DOS prompt and the cursor: 


A>_ 


| cursor 
MS-DOS prompt 


So when your prompt is A>, MS-DOS searches only the disk in drive A (the 
default drive) for files and programs—unless you tell it to search in another 
drive. 

To change the default drive, you simply type the letter of the desired drive, 
followed by a colon. For example, if you will be working primarily with files 
on drive B, it is easier to change the default drive to B, so that you won't have 
to type the letter b, followed by a colon, with every command and filename. 
Here’s how to change the default drive: 

B: 
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Command 


Just as you will run programs to create and update files containing your data, 
you will also need to run some special programs, called MS-DOS commands, 
that let you work with entire files. 


When you type MS-DOS commands, you are asking the computer to perform 
tasks. For example, when you use the diskcopy command to copy your MS- 
DOS master disk, you are using a file named diskcopy.exe, whose task is to 
copy the files on the MS-DOS disk. 


Other MS-DOS commands 

e Compare, copy, display, delete, and rename files 

e Copy, format, and label disks 

e Run your programs, as well as those supplied with MS-DOS 
e List directories for disks 

e Set the date and time 

e Set printer and screen options 


You’ll learn more about MS-DOS commands in Chapter 4, "Using 
Commands.” But for more detailed descriptions of commands, see the MS-DOS 
User's Reference. 


Devices 


Whenever you use your computer, you supply the information (input) and 
expect a result (output). Your computer uses pieces of hardware called devices 
to receive input and send output. 

For example, when you type a command, your computer receives input from 
your keyboard and disk drive, and usually sends output to your screen. It can 
also receive input from a mouse, or send output to a printer. Some devices, 
such as disk drives, perform both input and output. 


Device Names 


Device names are special names given to each device that your computer 
"knows" about. An example of a device name is LPT1, which stands for the 
first parallel lineprinter connected to your computer. 
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When you add a new device, such as a mouse, to your computer, you 
sometimes need to tell MS-DOS about it by setting up (configuring) your 
computer for that device. Refer to the information that came with your device, 
or to the MS-DOS User's Reference, for more information on configuring your 
computer for devices. 


Error messages 


If you or your computer makes a mistake when using a device or MS-DOS 
command, MS-DOS displays an appropriate error message. Error messages 
apply to general errors (such as misspelling a command) or to device errors 
(such as trying to use a printer that is out of paper). For a complete list and 
explanation of each MS-DOS error message (device and general), see the MS- 
DOS User's Reference, Appendix F. 


Memory 


Memory is the place in your computer where information is actively used. 
When you run a program, MS-DOS stores that program and the files it uses in 
the computer’s available memory. Some programs and files use more memory 
than others, depending on how large and complex they are. 


Keys You Use with MS-DOS 


Now that you've learned about MS-DOS terms, you can learn about the keys 
you will be using with the MS-DOS operating system. 
In addition to the keys you'd find on a typewriter, your computer keyboard has 
some keys that have special meanings to MS-DOS. 
First, note that there are two important differences between a typewriter 
keyboard and a computer keyboard: 
A computer understands the difference between a one and a 
1 lowercase L. Be sure you don’t type a lowercase L when 
you mean a one. 
[o] Capital O and zero may look alike, but they have different 
0 meanings to a computer. Many computers display a zero 
with a diagonal line (Ø) through it. Make sure you type the 


correct letter or number when you give commands to MS- 


DOS. 
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The Return Key 


RETURN 


Press the RETURN key after you type commands. When you 
press the RETURN key after typing acommand, MS-DOS 
performs the command. 


Keys that Move the Cursor 


The spAceBaR moves the cursor to the right. 


Use the BAcKsPACE key to correct typing mistakes on the 
current line. The Backspace key deletes characters as it 
moves the cursor to the left. 


To move the cursor to the left or right without deleting any 
characters, you must use the direction keys. Direction 
keys move the cursor right, left, up, and down. They do 
not affect the characters that are displayed. Some 
programs ignore these keys or do not use them. In these 
manuals, the direction keys are also referred to as the 
RIGHT, LEFT, UP, and DOWN arrow keys. 


Control Key Combinations 


CTRL 


The controt key has a special task. It lets you give complex 
commands to your computer by pressing only two or three 
keys. You must hold down the controL key while you press 
another key. That is, you use the conTRoL key as you would 
the sHiFT key. 

When you press the controL key and the s key at the same 
time, you can stop the scrolling of the screen display. Then 
to continue scrolling, press CONTROL-s again. 
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a When you press the controt key and the c key at the same 
time, you can stop a command. 


> z If you want to restart MS-DOS, press the CoNTROL, ALT, and 
DELETE keys at the same time. 


In this chapter, you’ve learned some of the MS-DOS special terms and seen 
what the keys on your keyboard can do. Now you are ready to go on to 
Chapter 2, "Learning About Disks, Files, and Directories.” There you’ll learn 
about floppy disks and hard disks, about formatting your disks, and about 
naming your files. 


2 Learning About Disks, Files, 


and Directories 


In this chapter you will learn about 


5.25-inch floppy disks 
3.5-inch disks 

Hard disks 

Filenames 


Directories 
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Floppy Disks 


A floppy disk is a flexible, magnetized plastic disk. A double-density floppy 
disks disk can store up to 400 single-spaced pages of text. A high-density disk 
can store about three times that amount. Every floppy disk is enclosed in its 
own protective cover. The front of this cover is smooth, while the back has 
visible seams. You should always place labels on the front of the cover, at the 
top, so that the label doesn’t touch the magnetic surface of the disk. It’s also a 
good idea to use a felt-tip pen when writing on labels—a pencil or ballpoint pen 
can damage the disk if you press too hard. 
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You should store floppy disks in a safe place, away from dust, moisture, 
magnetism, and extreme temperatures. Be sure to label each disk you use, since 
labels help you identify what files are on the disk and remind you that the disk 
has information stored on it. 
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Disk Protection 


Labels help you keep track of the information on your disks, but you may also 
need to protect the disks themselves. Some floppy disks are protected, letting 
you examine information on them without letting you change anything. These 
are called write-protected disks. 


Floppy disks can be write-protected in one of two ways. Some have a small 
piece of tape, called a tab, covering a notch on the right side of the disk. You 
can copy information onto a write-protected disk by first removing the write- 
protect tab; however, you should consider why the disk was protected—before 
you change its contents. After you have copied or changed a write-protected 
disk it’s always a good idea to replace the write-protect tab. 
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If a disk does not have a wmite-protect notch, it is permanently write-protected. 
Many application programs, including this version of MS-DOS, come on write- 
protected disks that protect the files from being destroyed accidentally. 


3.5-inch Disks 


The MS-DOS 3.3 operating system also supports 3.5-inch disks, which, like 
5.25-inch floppy disks, are portable magnetic disks. Data on 3.5-inch disks is 
more densely packed, so depending on the style, a single 3.5-inch disk can store 
as much (or more) data as a high-density floppy disk. 


These smaller disks, sometimes called microfloppies, have rigid plastic covers 
with metal shields that guard the disk from dirt and fingerprints. When you 
place the disk into the disk drive, the computer automatically moves this shield 
aside to read the disk. 


shield 





Front 
write-protect tab Back 
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Note that 3.5-inch disks have a write-protect notch. This notch can be covered 
with a built-in tab. As with 5.25-inch floppy disks, if the write-protection notch 
is covered by the tab, no data can be written to the disk. 


Be sure to label your 3.5-inch disks and store them in a safe place. As with 
5.25-inch floppy disks, extreme temperatures, magnetism, dust, and 
fingerprints can all harm your data on a disk. 


Note MS-DOS works virtually the same way with both 3.5-inch and 5.25- 
inch floppy disks. So in this documentation, the term floppy disk is used to 
mean either of these two types of disks. 


Hard Disks 


In addition to floppy disks, some computers use a hard disk, which can store 
much more information than a floppy disk. Computers also take less time to 
find information stored on a hard disk than on a floppy disk. A hard disk is 
usually built into the computer. Such a system might look like this: 
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Hard disk drive 
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When you store application programs, including MS-DOS, on your hard disk, 
you should keep a backup copy of the programs on a floppy disk in case the 
information on the hard disk is accidentally damaged or destroyed. (For more 
information about making a backup copy of your MS-DOS disk see Chapter 3, 
"Getting Started.") 


The Format Command 


Before you can use your new disks for storing information, you must format 
them. You do this with the format command, a special program that structures 
a disk so that MS-DOS can find information on it. The format command also 
checks the disk for defective spots. 


You can format both floppy and hard disks. But remember that if a disk is not 
blank, formatting it destroys any data already on the disk. 


You will learn more about the format command in Chapter 4, "Using 
Commands.” 


How to Name Your Files 


When naming a file, you may have trouble finding a name that uniquely 
identifies the file’s contents. Dates, for example, are often used in filenames; 
however, they take up several characters, leaving you with little flexibility. 
Other common names for files are words like budget, finances, analysis, report, 
etc. These kinds of filenames identify the contents, but leave little room for 
dates. So the secret is to find a compromise—a point where you can combine a 
date with a word, creating a unique filename. 


The name of a typical MS-DOS file (see Chapter 1) looks like this: 


customer.lst 


filename filename extension 


Notice that the filename was typed in lowercase letters. You can type filenames 
in uppercase or lowercase letters, even though MS-DOS converts them into 
uppercase letters. Some more examples of filenames are: 


budget. 86 
takeover.bid 
june86 
finances.doc 
schedule.may 
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Many of your filenames will contain onl letters and numbers. But you may also 
use any of the following symbols (and letters) in your filenames and 
extensions: 


A—Z a—z0—9$ %'’@{}~*!#()& 


Warning Some applications may not let you use all of these symbols. If in 
doubt use only letters and numbers. 


Invalid Filenames 


Although you do have some freedom when naming your files, there are certain 
names that you may not use, because MS-DOS reserves them for specific 
devices that your computer uses. These invalid names are aux, clock$, com, 
con, lpt, Ist, nul, and prn. You may use these names as extensions (except for 
clock$), but remember not to use them to name your files. 


Directories 


The names of your files are kept in a directory on each disk. The directory also 
contains information on the sizes of the files, and the dates they were created 
and updated. 

If you want to know what files are on your disk, you can use the dir command. 
This command tells MS-DOS to display all the files in a specific directory on a 
disk. For example, if your MS-DOS disk is in drive A and you use the dir 
command, the directory display would look similar to this: 


Volume in drive A is DOS 3-3 
Directory of A:\ 


COMMAND COM 23612 7-15-87 12:00p 


ANSI SYS 1651 7-15-87 12:00p 
ATTRIB EXE 8234 7-15-87 12:00p 
BACKUP EXE 22906 7-15-87 12:00p 
CHKDSK EXE 9680 7-15-87 12:00p 
FC EXE 14446 7-15-87 12:00p 
DISKCOPY EXE 3936 7-15-87 12:00p 
DRIVER SYS 1102 7-15-87 12:00p 
EDLIN EXE 7356 7-15-87 12:00p 
FDISK EXE 16444 7-15-87 12:00p 
FIND EXE 6403 7-15-87 12:00p 
GRAFTABL EXE 8210 7-15-87 12:00p 


GRAPHICS EXE 13170 7-15-87 12:00p 
JOIN EXE 8942 7-15-87 12:00p 
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KEYBDV EXE 2850 7-15-87 12:00p 
KEYBFR EXE 2912 7-15-87 12:00p 
KEYBGR EXE 2904 7-15-87 12:00p 
KEYBIT EXE 2856 7-15-87 12:00p 
KEYBSP EXE 2947 7-15-87 12:00p 
KEYBUK EXE 2850 7-15-87 12:00p 
LABEL EXE 2750 7-15-87 12:00p 
MODE EXE 13652 7-15-87 12:00p 
RECOVER EXE 4145 7-15-87 12:00p 
REPLACE EXE 4852 7-15-87 12:00p 
RESTORE EXE 21360 7-15-87 12:00p 
SHARE EXE 8544 7-15-87 12:00p 
SUBST EXE 9898 7-15-87 12:00p 
TREE EXE 8556 7-15-87 12:00p 
RAMDRIVE SYS 6454 7-15-87 12:00p 
XCOPY EXE 5396 7-15-87 12:00p 
DISKCOMP EXE 3808 7-15-87 12:00p 
ASSIGN COM 1523 7-15-87 12:00p 
MORE COM 282 7-15-87 12:00p 
PRINT EXE 8824 7-15-87 12:00p 
SORT EXE 1898 7-15-87 12:00p 
FORMAT EXE 10973 7-15-87 12:00p 
SYS COM 4607 7-15-87 12:00p 


37 File(s) 17408 bytes free 


Note The file sizes and dates you see on your screen may differ from the 
ones shown here, depending on your version of MS-DOS. Don’t worry, though. 
Such variations do not affect the way you use MS-DOS or the way MS-DOS 
responds to your commands. 


You can also get information about any file on your disk by typing the dir 
command followed by a filename. For example, to display directory 
information for a file named schedule, you could use the following command: 


dir schedule 


MS-DOS would respond by displaying the filename schedule followed by the 
file’s size in bytes and the date and time it was last changed; for example, 


SCHEDULE. TXT 3698 8-7-874:1llp 


So far you have learned the basic background information that you need in 
order to use the MS-DOS operating system. In the final three chapters of this 
guide, you’ll learn to make your computer work for you, while you build a 
working knowledge of MS-DOS. 


3 Getting Started 


In this chapter you will learn 


e Howto start MS-DOS 

e How to quit MS-DOS 

e Howto make a backup copy of your MS-DOS disk 
e What to do if you have a hard disk 

e What to do if you have only one floppy disk drive 


How to Start MS-DOS 


The first two chapters in this manual introduced you to the fundamentals of 
MS-DOS. Now it’s time to put your new knowledge to the test. You'll start by 
loading MS-DOS into your computer’s memory. 


To start MS-DOS, just follow these steps (these steps work for computers that 
have either hard disks or floppy disks): 


1. First, make sure your computer is tumed off. 
2. Take the MS-DOS master floppy disk out of the protective jacket. 


3. Insert this disk into drive A. (Refer to your computer manual for the 
correct drive.) 


4. Close the disk drive door. 
5. Tum on the power for your monitor and your computer. 


The light on the disk drive should glow, and you should hear some whirring 
noises as your computer "reads" the disk. You should then see the following on 
your screen: 


Current date is Tue 1-01-1980 
Enter new date (mm-dd-yy): 


MS-DOS asks you to provide the date. 
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1. Type the date. For example, if the date is July 6, 1986, you simply type the 
following command, then press the RETURN key: 


07-06-86 


If the date is already correct, or you do not want to answer this prompt, 
press the RETURN key to move to the next step. 


2. Type the time according to a 24-hour clock. For example, if it is 
1:30 P.M., type the following, then press the RETURN key: 


13:30 


If the tume is already correct, or you do not want to answer this prompt, 
press the RETURN key. 


MS-DOS does not accept your command until you press the RETURN key. 


Note If you make a mistake when you are typing the date or time, simply 
backspace over the mistake and retype (as you use the BacksPACE key, you will 
notice that the characters disappear). If you make a mistake and have already 
pressed the RETURN key, press the CONTROL-ALT-DELETE keys simultaneously to 
restart MS-DOS and try again. 


Your screen should look something like this (your time and date may be 
different, depending on what you typed in steps 1 and 2): 


Current date is Tue 1-01-1980 
Enter new date (mm-dd-yy): 07-06-87 
Current time is 0:00:45:10 

Enter new time: 13:30 


Microsoft(R) MS-DOS (R) Version 3.30 
(c) Copyright Microsoft Corp 1981-1987 


A>_ 


In this example, the default drive is drive A, so the A> is the standard MS-DOS 
prompt. When you see A> prompt, MS-DOS is waiting for instructions from 
you. 
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Before you start giving these instructions, however, you might like to know 
how to quit MS-DOS. 


How to Quit 


There is no "quit" command in MS-DOS, but you can end your MS-DOS 

session easily by following these steps: 

1. Make sure that your last command is finished. You should see the MS- 
DOS prompt (for example, A>) on the screen. 


2. Remove the floppy disks from the drives, put them back in their protective 
jackets, and store them in a safe place, away from dust, moisture, and 
magnetism. 


3. Tum off your computer. 
4. Tum off your monitor. 


How to Make a Backup Copy of Your 
MS-DOS Disk 


In this section you’]] learn how to make a backup copy of your MS-DOS disk if 
you have two floppy disk drives. If you have a hard disk, read "If You Have a 
Hard Disk." If you have only one floppy disk drive, read this section, then "If 
You Have Only One Floppy Disk Drive" at the end of this chapter. 


MS-DOS comes with a program named diskcopy that lets you copy the 
contents of disks. You need not format your blank disks before you use the 
diskcopy command. 

Making a backup copy of your MS-DOS master disk is easy: 

1. Start MS-DOS with the MS-DOS master disk in drive A. 

2. Make sure that a blank disk is in drive B. 

3. Atthe MS-DOS prompt, type the following: 


diskcopy a: b: 


4. Press the RETURN key. 
If you make a mistake when typing this command, such as misspelling it, 
MS-DOS displays the following error message: 
Bad command or file name 
A>_ 
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To fix this error, retype the command, and check the spelling before you 
press the RETURN key. 
Your screen should look like this: 


A> diskcopy a: b: 

Insert SOURCE diskette in drive A: 
Insert TARGET diskette in drive B: 
Press any key when ready . 


Note If you have only one floppy disk drive, MS-DOS prompts you to 
insert the drive A disk. For more information, see the section, "If You 
Have Only One Floppy Disk Drive," later in this chapter. 


5. Press the spacenakr to start the diskcopy program. 
The disk copying process takes time, so you'll have to wait awhile. 
When the diskcopy program is complete, MS-DOS asks 


Copy another? (Y/N) 
6. Type N (for No) to end the diskcopy program. 


You now have two MS-DOS disks: the MS-DOS master disk and the copy you 
just made. 
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Label the new disk, and cover its write-protect notch with a write-protect tab. 
Then put your MS-DOS master disk in a safe place, away from dust, moisture, 
and magnetism. If anything should happen to the copy you have just made, 
you’ ll have to use the master disk to make another copy. 


Note Always use your backup copy of the MS-DOS master disk. Keep the 
master disk in a safe place. 


If You Have a Hard Disk 


If your computer has a hard disk, you should copy all the files from the MS- 
DOS master disk onto the hard disk. Then each time you start MS-DOS, you 
won't need to use a floppy disk; instead, you’ll be able to start MS-DOS 
directly from the hard disk. When you have copied the MS-DOS files onto your 
hard disk, the original floppy disk will be your backup copy. 

But before you can copy the MS-DOS files onto your hard disk, you may need 


to configure it first. To find out whether you need to do this, see the section 
about configuring your hard disk in the MS-DOS User's Reference. 


Warning Whenever you format a disk, you destroy its files. It’s a good idea 
to copy any files from your hard disk onto floppy disks before you format the 
hard disk (to learn how to copy files, see Chapter 4, "Using Commands"). Once 
you have formatted your hard disk you should never have to format it again. 


The following example assumes that your hard disk is named drive C. Refer to 
the documentation that came with your computer to find out the name of your 
hard disk; then follow these steps to format it: 


1. Start MS-DOS, and type the date and time. 
2. Be sure that your MS-DOS master disk is in drive A. 


3. Atthe MS-DOS prompt, type the following command, then press the 
RETURN key: 


format c: /v /s 
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6. 


If you’ve typed the command correctly, MS-DOS formats the disk in drive 
C. However, if you make a mistake when typing the command line, such 
as misspelling it, MS-DOS displays the following message: 

Bad command or file name 

A>_ 

To fix this error, retype the command, and check the spelling before you 
press the RETURN key. If you have typed the command correctly, MS-DOS 
displays a message showing you its progress as it formats your hard disk. 


When the format process is complete, MS-DOS displays the following 
prompt: 
Volume label (11 characters, ENTER for none}? 


Type the name that you want to use to identify the hard disk (for example, 
HARD DISK), and press the RETuRN key. 
MS-DOS asks 


Format another? (Y/N) 


Type N (for No) to end the format program. 


To copy files onto your newly formatted hard disk, you must use the copy 
command. This command is automatically loaded into your computer’s 
memory when you start MS-DOS. 


Note You cannot copy files onto your hard disk by using the diskcopy 
command. The diskcopy command works only for copying one floppy disk to 
another. 
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To copy your MS-DOS master disk onto a hard disk (drive C), follow these 
steps: 


1. Make sure that the MS-DOS master disk is in drive A. 
2. At the MS-DOS prompt, type the following command: 


copy a:*.* c: 


This command tells MS-DOS to copy all files on drive A to drive C. 
3. Press the RETURN key. 


The copy program then lists each file on the screen as it is copied onto the new 
disk. When the process is complete, MS-DOS shows you how many files it has 
copied. 

You now have two MS-DOS disks: the MS-DOS master disk and the copy you 
have just made on your hard disk. 





Master disk copied to hard disk 


Now, put the master disk in a safe place, away from dust, moisture, and 
magnetism. If anything happens to your hard disk, you will have to use the 
master disk to make another MS-DOS backup copy. 
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If You Have Only One Floppy Disk Drive 


If your computer has only one floppy disk drive, you can still use MS-DOS 
commands as you would on a system with more than one drive, but you must 
also specify a drive name when you type a command. By specifying the drive 
letter, you tell your computer to perform the command on that drive. The drive 
names A and B then represent the disks that you put into the single drive. In 
response to your commands, MS-DOS then prompts you to insert the proper 
disk, as in the following example: 


A> format a: /v 
Insert new diskette for drive A: 
and strike ENTER when ready _ 


If you specify drive B in a command when you have only one drive, MS-DOS 
prompts you to insert the disk for drive B. 

To make a copy of your MS-DOS disk if you have only one floppy disk drive, 
type the following at the MS-DOS prompt: 


diskcopy a: b: 
MS-DOS responds with the following message: 


Insert SOURCE diskette in drive A: 
Press any key when ready . 


Remove the MS-DOS disk, put the blank disk into the drive, and press any key. 
You may need to reinsert the disks for drives A and B several times to 
complete the copy process. 


Note The letter in the system prompt represents the default drive; it does not 
represent the last disk used. 


You now know how to start and quit the MS-DOS operating system, and 
you’ve used some simple commands to copy and format your disks. In the next 
chapter, you’ll learn to use more MS-DOS commands. As you read about these 
commands and start to use them, you’ll begin to understand how the MS-DOS 
operating system works. And once you understand the operating system, you'll 
see what it can do for you. 


4 Using Commands 


In this chapter you will learn 


° How to use file commands 
e Howto pnnt files 


e How to use disk commands 


File Commands 


You can use several MS-DOS commands to manage your files. Some of the 
more common commands are dir, copy, del, rename, and print. 


Note The examples in this chapter assume that drive A is the default drive. 
Also, many of these examples use filenames which are intended for illustrative 
purposes only—to use these commands, you would substitute the name of a file 
on the default disk. 


The Dir Command 


If you want to find out what files are on a disk, you can list its directory by 
using the MS-DOS dir command. For example, to display the directory of the 
disk in drive B, you would use the following command: 


dir b: 


Grow me \ ...of the disk in drive B. 
the directory... 


You could also display the directory on the hard disk by using the drive letter C 
instead of B with the dir command. If you use the dir command without a 
drive letter, MS-DOS lists the directory of the disk in the default drive. 
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Example 


Suppose you want to see how many files are in the directory of the MS-DOS 
disk in drive A. To display this directory you would simply follow these steps: 


1. Make sure the MS-DOS disk is in drive A. 

2. Make sure the disk drive door (for drive A) is closed. 

3. At the MS-DOS prompt, type the following command, then press the 
RETURN key: 
dir 

4. Ifthe disk drive door (for drive A) is open when you try to use this 
command, MS-DOS will display the following error message: 


Not ready error reading drive A 
Abort, Retry, Ignore?_ 


To fix this error, you simply close the door for drive A and type R (for 
Retry). 


5. MS-DOS then displays the directory. If necessary, you can stop the 
directory listing from scrolling by pressing conTRoL-s To view the rest of 
the display, you simply press CONTROL-s again. 


Your screen should look similar to this: 


Volume in drive A is DOS 3-3 
Directory of A:\ 


COMMAND COM 23612 8-21-87 12:00p 


ANSI SYS 1651 8-21-87 12:00p 
ATTRIB EXE 8234 8-21-87 12:00p 
BACKUP EXE 22906 8-21-87 12:00p 
CHKDSK EXE 9680 8-21-87 12:00p 
FC EXE 14446 8-21-87 12:00p 
DISKCOPY EXE 3936 8-21-87 12:00p 
DRIVER SYS 1102 8-21-87 12:00p 
EDLIN EXE 7356 8-21-87 12:00p 
FDISK EXE 16444 8-21-87 12:00p 
FIND EXE 6403 8-21-87 12:00p 
GRAFTABL EXE 8210 8-21-87 12:00p 
GRAPHICS EXE 13170 8-21-87 12:00p 
JOIN EXE 8942 8-21-87 12:00p 
KEYBDV EXE 2850 8-21-87 12:00p 
KEYBFR EXE 2912 8-21-87 12:00p 
KEYBGR EXE 2904 8-21-87 12:00p 


KEYBIT EXE 2856 8-21-87 12:00p 


KEYBSP 
KEYBUK 
LABEL 
MODE 
RECOVER 
REPLACE 
RESTORE 
SHARE 
SUBST 
TREE 
RAMDRIVE 
XCOPY 
DISKCOMP 
ASSIGN 
MORE 
PRINT 
SORT 
FORMAT 
SYS 


EXE 2947 
EXE 2850 
EXE 2750 
EXE 13652 
EXE 4145 
EXE 4852 
EXE 21360 
EXE 8544 
EXE 9898 
EXE 8556 
SYS 6454 
EXE 5396 
EXE 3808 
COM 1523 
COM 282 
EXE 8824 
EXE 1898 
EXE 10973 
COM 4607 
37 File(s) 


8-21-87 
8-21-87 
8-21-87 
8-21-87 
8-21-87 
8-21-87 
8-21-87 
8-21-87 
8-21-87 
8-21-87 
8-21-87 
8-21-87 
8-21-87 
8-21-87 
8-21-87 
8-21-87 
8-21-87 
8-21-87 
8-21-87 


17408 bytes 
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12:00p 
12:00p 


free 


Note The file sizes and dates you see on your screen may differ from the ones 
shown here, depending on your version of MS-DOS. Don’t worry, though. 
Such variations do not affect the way you use MS-DOS or the way MS-DOS 


responds to your commands. 


The Copy Command 


If you need to copy files, you can use the copy command to copy one or more 
files, either on the same disk or from one disk to another. For instance, suppose 
you need a copy of a file named sales.doc that you have on a disk in drive A, 
and suppose you want to call this new copy monthly.rpt. 


Example 


To copy the sales.doc file and call the new copy monthly.rpt you would just 
follow these steps: 


1. 


2. 


Make sure that the disk with the sales.doc file is in drive A and that A is 
the default drive. 
At the MS-DOS prompt, type the following command: 


copy sales.doc monthly.rpt 


Press the RETURN key. 
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You cannot give the new copy of a file the same name as the original. You 
can, however, copy a file from one disk to another and keep the same filename. 
For example, to copy a file from the disk in drive A to the disk in drive B, use 
the following command: 


copy a:sales.doc b:sales.doc 


Make a copy Name the copy of the file 
of a file... “sales.doc” as well,... 
..named “sales.doc” ..and put it on the disk in drive B. 
on drive A. 


Note In the previous example, if A is the default drive (that is, if the prompt 
is A>), you needn’t type the letter A, followed by a colon, before the first 
filename. If you don’t specify a new name, the copy will also have the name of 
the original file. For example, the following commands all produce the same 
result: 


copy a:sales.doc b:sales.doc 
copy sales.doc b:sales.doc 
copy sales.doc b: 


Again, by substituting the drive letter C for B, you could copy the sales.doc file 
to drive C. l 


The Del Command 


Just as you may need to make copies of files, you may also need to remove old 
or unnecessary files to clean up your file system. When you want to erase a file 
from a disk, you can use the MS-DOS del command. Remember, though, that 
the del command permanently erases the file. To delete an old sales.doc file 
from the disk in drive B, at the MS-DOS prompt you would use the following 
command: 


del b:sales.doc 

Delete a file... Teori “sales.doc” from the disk in drive B. 
You could also delete a file named sales.doc from drive C by simply 
substituting the drive letter C for B. 


Example 


Suppose you have an old copy of the sales.doc file that you no longer need. To 
delete this file from the disk in the default drive, you would just follow these 
steps: 
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1. Make sure that the disk with the sales.doc is in the default drive. 
2. At the MS-DOS prompt, type the following command: 


del sales.doc 


3. Press the RETURN key. MS-DOS then deletes the sales.doc file from the 
disk. 


Note The del command does not work if you type the word delete. You can, 
however, substitute the word erase in place of the del command. 


The Rename Command 


Occasionally, you may want to change the name of a file. For example, 
suppose you have a file named monthly.rpt on a disk. When you add other 
monthly reports to your disk, you may want to change the name of the original 
file to something more specific. To change the name to annual.rpt, for 
instance, you would use the following command: 


rename monthly. rpt annual.rpt 


Change the name |...from .. to “annual.rpt.” 
of a file... “monthly.rpt”’... 


You can only rename files on the same disk, so you cannot change 
a:monthly.rpt to b:monthly.rpt or c:monthly.rpt. 


Example 


Suppose you want to rename a file named payroll.doc, on the disk in the default 
drive, to salary.doc. You would simply follow these steps: 


1. Make sure that the disk with the payroll.doc file is on the disk in the 
default drive (A). 


2. At the MS-DOS prompt, type the following command: 
rename payroll.doc salary.doc 


3. Press the RETURN key. 


Note The rename command can be abbreviated to ren. 
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The Type Command 


If you want MS-DOS to display a file that contains text (often called a text file) 
on the screen, use the type command. For example, say you have created a file 
named phone.Ist on the disk in drive A, and you want to check one of the phone 
numbers. To display the file on the screen, you would use the following 
command: 


type a:phone. lst 





Display on ..the file named “phone.!/st” 
the screen... \that is on the disk in drive A. 
Example 


Suppose you want to check your employees’ salary figures. So you decide to 
look at a file named salary.doc that is on the disk in the default drive. To 
display the salary.doc file you would just follow these steps: 

1. Make sure that the disk with the salary.doc file is in the default drive (A). 


2. At the MS-DOS prompt, type the following command: 
type salary.doc 


3. Press the RETURN key. 


MS-DOS then displays the salary.doc file on the screen. 


If the salary.doc file is on drive B or C, you could easily type the drive letter, 
followed by a colon, with the type command. 


Hints If the file is too long to fit on the screen, remember that you can press 
CONTROL-S to prevent it from scrolling off the screen. When you press CONTROL-s 
again, the file will resume scrolling. 


MS-DOS displays only text files on the screen. So if you try to display a 
program file (one with an extension of .com or .exe), you will see only strange 
symbols on the screen. 


If you have an application program that creates files, you may need to run the 
application to view them. For example, if you use Microsoft Multiplan to create 
a file, Multiplan automatically adds the extension .mp to the filename. You 
would then have to start Multiplan to view the file. 
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The Print Command 


If you have a printer attached to your computer, you can print files with the 
MS-DOS print command. Assume, for example, that you have a file named 
invest.mnt and want to print it on your printer. You could use the following 
command: 


print invest.mnt 


Print a file (MS-DOS |...named “invest.mnt.” 
assumes this file 

is on the disk in the 

default drive)... 


Example 


Say you have a file that contains a list of investors and their phone numbers, 
and suppose you want to print this file and keep it near your phone. The file is 
named invest.mnt and is on the disk in drive B. Drive A is the default drive 
(A> is the prompt). To print the invest.mnt file, you would just follow these 
steps: 


Make sure that the MS-DOS disk is in drive A. 

Make sure that the disk with the invest.mnt file is in drive B. 

Check to see that your printer is on, has paper, and is ready to print. 
At the MS-DOS prompt, type the following command: 


A OLN J 


print b:invest.mnt 


o 


Press the RETURN key. 


6. MS-DOS prompts you for the name of the printing device connected to 
your computer (this name is usually the communications port that the 
printer cable connects to). Just type the name, or press the RETURN key to 
print to the default printer. 


If the master disk is not in drive A, MS-DOS prompts you to insert it in the 
drive. 


Hints While a file is being printed, you can type other commands to MS- 
DOS. You can even run other programs or create and modify files. But since 
printing a file takes a lot of your computer’s resources, your tasks may take 
longer if you try to do them while you are printing a file. So if you have a long 
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file to print, you might schedule the printing for when you plan to be away 
from your computer. 


In addition, if you want to print a file that you’ve created with an application 
program, you may also have to use the application program’s print command to 
print the file. 


Disk Commands 


This section presents two commands that you use for disks: format and 
diskcopy. 


The Format Command 


When you purchase new disks, they are blank and unformatted. You must 
format them before MS-DOS can use them. Formatting structures a disk so 
that MS-DOS can find and store information on it; formatting also checks the 
disk for defective spots. You can format a disk by using the format command. 


To format a blank disk in drive B, you would use the following command: 


format b: /v 
| and ask for a label. 
..on drive B,... 
Format a disk... 


Note If you have only one disk drive, MS-DOS prompts you to insert the disk 
that you want to format. See "If You Have Only One Floppy Disk Drive," in 
Chapter 3, "Getting Started." 


You can also format a blank disk in such a way that some special MS-DOS 
files are copied onto it during formatting. These files are necessary only if you 
want to use the disk to start MS-DOS. To format a blank disk in drive B and 
include these special MS-DOS files, you would use the following command: 


format b: /v /5 


Format ..and copy the special MS-DOS files. 
a disk... „ask for a label... 
..on drive B,... 
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If you don’t want to use the disk to start MS-DOS, you don’t need to specify 
the /s option when formatting the disk. If you have a disk and don’t know 
whether you can use it to start MS-DOS, put the disk into drive A and press the 
CONTROL-ALT-DELETE key combination. If the disk does not contain the system 
files, MS-DOS displays an error message. 


Example 


Suppose you need to create a new data disk to hold some tax records, but you 
don’t want to copy the special MS-DOS files when formatting the disk. To 
format and label a blank disk (in drive B) without including the special MS- 
DOS files, you simply follow these steps: 

1. Make sure that the MS-DOS disk is in drive A. 

2. At the MS-DOS prompt, type the following command: 


format b: /v 


3. Press the RETURN key. 
Your screen should look like this: 


A>format b: /v 
Insert new diskette for drive B: 
and strike ENTER when ready _ 


4. Insert a blank disk in drive B. 
5. Press the RETURN key to start the format process. 
When formatting is complete, MS-DOS displays the following prompt: 


Volume label (11 characters, ENTER for none)? 


6. Type a label that identifies the contents of this disk (for example, DATA 
DISK), and press the RETURN key. MS-DOS then asks 


Format another? (Y/N) 


7. Type N (for No) to exit the format program. 


In this example, you learned how to format a floppy disk that was in drive B, a 
floppy disk drive. To format your hard disk, you should follow the instructions 
in Chapter 3, "Getting Started." 
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Now your disk is formatted and ready to use. Be sure to label it on the outside 
cover, and remember to include the volume label that you used in step 6. The 
label will remind you that you have formatted the disk, and will help you 
identify its contents. 


IMENEM on 
L1OC-0 | 





()- 





Warning The format program destroys any information already on a disk. 
It’s a good idea to check the directory of a disk before you format it, just to 
make sure you won’t be destroying any important files. 


The Diskcopy Command 


You may often need to make copies of entire disks instead of individual files. 
You can do this easily with the MS-DOS diskcopy command. To use the 
diskcopy command, you must have 


e an MS-DOS disk 
e adisk you want to copy 


e a blank disk to put the copy on 


To copy the contents of a disk in drive A to a disk in drive B, you would use 
the following command: 


diskcopy a: b: 


Copy a dst. ig drive B. 
from drive A... 
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Note You cannot use the diskcopy command to copy the contents of a floppy 
disk to or from a hard disk. Instead, you must use the copy command. 


Example 


Suppose you want to bring a data disk with you on a business trip, but you 
don’t want to take your original disk because it might get damaged. All you 
have to do is use the diskcopy command to make a copy of the disk. For 
example, to copy the contents of a disk in drive A to a disk in drive B, you 
simply follow these steps: 


1. Put your MS-DOS disk in drive A. 

2. At the MS-DOS prompt, type the following command: 
diskcopy a: b: 

3. Press the RETURN key. 
Your screen should look like this: 
A>diskcopy a: b: 
Insert SOURCE diskette in drive A: 
Insert TARGET diskette in drive B: 
Press any key when ready . 


4. Remove the MS-DOS disk from drive A, replacing it with the disk you 
want to copy (SOURCE). Then place a blank disk (TARGET) in drive B. 


5. Press the spacear to start the diskcopy process. 
When the disk has been copied, MS-DOS asks 
Copy another? (Y/N) 

6. Type N (for No) to exit the diskcopy program. 


If you’d like more detailed information about the commands in this chapter, see 
your MS-DOS User's Reference. But if you are satisfied that you know enough 
about these commands, you can go on to the next chapter, where you'll learn 
how to run some applications with MS-DOS. 


5 Using Applications 
with MS-DOS 


In this chapter you will learn some common uses of MS-DOS, such as 


e Running application programs 
e Creating a file with Edlin 


How to Run Application Programs 


MS-DOS lets you run many different application programs, including 
spreadsheets, word processing programs, and graphics packages. These 
application programs can help you in a number of ways. For instance, they can 
help you balance a budget, figure income taxes, or manage information, such as 
stocks, monthly reports, and address lists. 

Once you have started MS-DOS, you can run an application program, as 
follows: 

1. Ifdrive A is not the default drive, change the default drive to drive A. 

2. Put the application program disk in drive A (the default drive). 

3. Type the name of the application program you want to run. 
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Press the RETURN key. 
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Example 


Suppose you have a word processing application called Phrase that you want to 
use to write a monthly status report. 


To start Phrase in MS-DOS, you would follow these steps: 


1. Make sure that the default drive is drive A by typing the letter A followed 
by acolon. 


2. Put your Phrase disk into drive A. 

3. Type the name phrase (supposing phrase is the word used to start the 
application). 

4. Press the reTuRN key to start Phrase, which you could then use to create, 
edit, format, or print your status report. 


If you want to run an application that is on your hard disk (drive C), follow 
these steps: 


1. Change the default drive to C, the drive that contains the application 
program. 

2. Type the name of the application program you want to run. 

3. Press the RETURN key. 


Example 


Suppose you have a graphics program called Canvas stored in drive C, and you 
want to use it to create a chart showing the current month’s sales data. 


To start Canvas in MS-DOS, you would follow these steps: 


1. Change the default drive to drive C by typing the letter C, followed by a 
colon. 


2. Type canvas (supposing canvas is the word used to start the application.) 
3. Press the RETURN key to start Canvas. 


You could then use Canvas to create your chart. 
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A Note about Using Application Programs 


After quitting some application programs, especially programs that use a lot of 
memory, you may receive the following error message from MS-DOS: 


Non-System disk or disk error 
Replace and strike any key when ready 


This message doesn’t mean you have ruined your application program or your 
computer. It occurs because your application used so much of the computer’s 
memory that it wrote over the MS-DOS command.com file. To fix the error, 
you simply reinsert a disk that contains a copy of command.com in the default 
drive (this command.com file must be the same version you used to start MS- 
DOS). You then press any key when you're ready to continue using your 
computer. 


How to Create a File with Edlin 


MS-DOS includes a line-editing program called Edlin that lets you create and 
edit files. Edlin is called a line editor because it lets you edit files line by line. 


To help you learn how to use Edlin, the following section takes you through a 
sample editing session in which you’l] use Edlin to create a small file. 


Suppose a client asks you to write a catchy advertisement for an electric pencil 
sharpener, so you decide to create a file named pencil.ad on the disk in the 
default drive. You want the file to contain the following lines: 


Introducing... 

The X-1000 Automatic Pencil Sharpener 
From Sharpe Office Supplies 

The World Leader in Office Sharpeware 
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The following example shows you how to start Edlin, create the pencil.ad file, 
and exit Edlin. All you have to do is follow these steps: 


1. 
2. 


Make sure the MS-DOS disk is in drive A. 


At the MS-DOS prompt, type the following command, then press the 
RETURN key: 


Edlin pencil.ad 


Since you are just creating the file, Edlin responds with the following 
message: 


New file 
* 


When you see the asterisk (*), type the letter J (for Insert) and press the 
RETURN key. You will see line number 1 (Edlin uses line numbers to help 
you edit, but they are not part of your file). 


Type the following lines. Remember to press the RETURN key after each 
line, including the last line. 


Introducing... 

The X-1000 Automatic Pencil Sharpener 
From Sharpe Office Supplies 

The World Leader in Office Sharpeware 


Note If you make a mistake when typing in a line, use the BAcKspace key 
to erase the mistake before you press the rETuRN key. If you do press the 
RETURN key before correcting the mistake, don’t worry about it—you’ll 
learn later how to correct a line. 


Your screen should look like this: 


A>Edlin pencil.ad 

New file 

aL 

:*Introducing... 

:*The X-1000 Automatic Pencil Sharpener 
:*From Sharpe Office Supplies 

:*The World Leader in Office Sharpeware 
Joek 


DUNE 


When you see 5*, press CONTROL-c to retum to the Edlin prompt (the 
asterisk). 
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5. If you made a mistake when typing a line (line 3, for instance), type the 
number 3, press RETURN, and retype the line (remember to press the RETURN 
key at the end of the line). 


6. Then at the asterisk (*), type the letter È (for End). You will then be 
returned to the MS-DOS prompt. 


You now have a file named pencil.ad on the disk in your default drive. If you 
type the MS-DOS dir command, you should see an entry for pencil.ad. You 
can also view this file by using the type command as follows: 


type pencil.ad 
To learn more about how to use Edlin, see the MS-DOS User's Reference. 


In this chapter, you’ve learned how to run application programs in MS-DOS, 
and how to use the line editor, Edlin. In the next and final chapter, you’ll learn 
how to set up MS-DOS for your needs, for the tasks that you want to do. 


6 Setting Up MS-DOS 


In this chapter you will learn about 


e The config.sys file 
e The autoexec.bat file 
e The differences between these two files 


This chapter discusses config.sys and autoexec.bat, two special files that you 
can use to set up MS-DOS. Yov’l still be able to use MS-DOS if you don’t 
have these files, but they will help you take greater advantage of the operating 
system as you run commands and application programs, and as you use 
devices. In addition to taking greater advantage of the operating system, these 
special files save you time, by doing tasks for you each time you start MS- 
DOS. 


The Config.sys File 


When you start MS-DOS, it automatically searches for a file named config.sys 
on your system disk. This file contains special commands that let you set up 
(configure) MS-DOS for use with devices of application programs. 


You can use the dir command to see whether the config.sys file is already on 
your MS-DOS disk. If the file isn’t on the disk, you can use Edlin to create it; 
if it is on the disk, you can use either the type command to display it, or Edlin 
to edit it. 
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Example 


Although your config.sys file should contain the following commands, you 
shouldn’t worry if the file contains more than these two commands: 


buffers=20 
files=20 
The command buffers=20 sets the number of buffers, or blocks of memory, 


that MS-DOS uses to store data. If your directory system is large, you might 
want to set the buffers number higher, say to 30. 


The second command in the config.sys file is files=20. This command sets the 
number of files that MS-DOS can have open at the same time. Programs such 
as spreadsheets and databases require several files to be open while they are 
running. If you don’t set a value for files in your config.sys file, MS-DOS 
assumes a value of 8, which would not be enough open files for a large 
program like a database. 


Note If you are using MS-DOS with Microsoft Networks, you should set the 
files command equal to 255. 


You may also want to add other commands to the file to configure MS-DOS for 
devices, such as a mouse. You should refer to the manual that came with the 
device, or to the MS-DOS User's Reference, for more information about how to 
do this. 


If you don’t have a config.sys file on your MS-DOS disk, simply follow these 
steps to create one: 


1. Type the following command line, then press the RETURN key: 
Edlin config.sys 
2. At the Edlin asterisk (*) prompt, type the letter / (for Insert) and press the 


RETURN key. 

3. Now on line 1, type the config.sys command buffers=20, then press the 
RETURN key. 

4. On line 2, type the command files=20, then press RETURN, followed by 
CONTROL-C. 


5. Then at the asterisk (*), type the letter E (for End). You will then be 
returned to the MS-DOS prompt. 
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MS-DOS performs the commands in the config.sys file only when you first 
start the system; therefore, for your changes to take effect, you must restart 
MS-DOS after editing this file. 


For more information about the config.sys file and the config.sys commands, 
see the MS-DOS User's Reference, Appendix B, "How to Configure Your 
System.” 


The Autoexec.bat File 


MS-DOS also searches for a second file when you start your computer. This 
file is called autoexec.bat. It performs any set of commands you would 
normally give when you start MS-DOS. For example, you might use the file to 
prepare MS-DOS for running an application program. 


If there is an autoexec.bat file on the disk when you start MS-DOS, MS-DOS 
does not automatically prompt you for the time and date at the beginning of 
your computer session. Therefore, unless you have an installed clock in your 
computer, it is a good idea to put the time and date commands in your 
autoexec.bat file. This way, MS-DOS will prompt you for the time and date, 
and will keep the time and date information current for the directory on your 
disk. 

To see if the autoexec.bat file is already on your MS-DOS disk, you simply 
type the dir command. If the file isn’t on the disk, you can use Edlin to create 
it, as you did with the config.sys file. If the autoexec.bat file is on the disk, you 
can use either the type command to display it, or Edlin to edit it. 


Examples 


For a computer with two floppy disk drives, a typical autoexec.bat file might 
contain the following lines: 


date 

time 

path=a: 

dir 

In this sample file, the date and time commands ask you to set the date and 
time each time you start MS-DOS. The command path=a: tells MS-DOS to 
look for commands or programs on drive A in addition to the default directory. 
The dir command displays the default directory of the disk in the default drive 
as soon as you start MS-DOS on your computer. 
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The next sample autoexec.bat file is for computers with one floppy disk drive 
and one hard disk drive. It might contain the following lines: 


date 

time 

path=c:;a: 

prompt=Sp$qg 

dir 

The commands in this autoexec.bat file differ slightly because the file is 
intended for computers with a hard disk. For instance, the path command line 
now contains c+, in addition to a:, since when you give a command or start an 
application, you may want MS-DOS to search two drives, first C, then A. 


Another new command in this file is the prompt=$p$g command, which tells 
MS-DOS to display the default drive and directory, followed by a greater-than 
sign (<), as the MS-DOS prompt. This prompt is handy because it reminds you 
what drive and directory you’re in at the moment. 

It doesn’t matter if your autoexec.bat file differs from the ones listed here, but 
it should at least include the time and date commands. Also, if you want to 
start a certain application program every time you start MS-DOS (for example, 
Microsoft Word), you could include the command to start that application 
(word) at the end of the autoexec.bat file. 


Once you become more familiar with MS-DOS, you will probably want to vary 
these commands, or include others. For more information about autoexec.bat 
files or the commands used in these examples, see the MS-DOS User's 
Reference. 


How These Special Files Differ 


MS-DOS uses the config.sys and autoexec.bat files in different ways because 
they perform different types of commands. While the autoexec.bat file may 
contain any MS-DOS command or program, the config.sys file may contain 
only a special set of configuration commands. 


In addition, you must restart MS-DOS to perform the commands in the 
config.sys file. But to perform the commands in the autoexec.bat file, you 
simply type the word autoexec. 
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Summary 


So far you have learned about the basics of the MS-DOS operating system, 
including some MS-DOS terms, the special keys on the MS-DOS keyboard, 
and two special MS-DOS files. 


You've also learned about: 


e Using disks, files, and directories 

e Starting MS-DOS 

e Using file and disk commands 

e Printing files 

e Running application programs 

e Using multitasking 

e Using Edlin 

e Creating config.sys and autoexec.bat files 


If you don’t remember everything about these topics, just refer to the 
appropriate sections to refresh your memory. It’s also a good idea to look ahead 
at the "Terms" section. There you can browse through the definitions and 
familiarize yourself with MS-DOS terminology. Then once you're confident in 
your abilities, you can go on to the more advanced MS-DOS User's Reference. 


In the User's Reference, you'll read and learn about multilevel directories, 
batch files, additional features of Edlin, and much more. Also, if you need a 
more detailed explanation or example of how to use a command, you can refer 
to the commands section of the MS-DOS User's Reference. So if this User's 
Guide hasn’t answered all your questions, you know where to look for help. 


Terms 


The following terms are used in the MS-DOS User's Guide: 
*,.* This abbreviation means all files in the directory. The command copy 


a:*.*b: means copy all files from the default directory of the disk in drive A to 
the disk in drive B. 


Application software Another name for software, programs, or application 
programs. Software is written in a computer language and consists of a series of 
instructions that tell the computer to perform tasks. 

Autoexec.bat A special MS-DOS file that you use to customize the MS- 
DOS operating system to your needs. See also Config.sys. 

Backup disk A copy of any disk you make with the diskcopy, copy, or 
backup command. (See the MS-DOS User’s Reference for more information 
on the backup command.) You should always make a backup copy of the MS- 
DOS master disk before you begin using MS-DOS on a routine basis. Store the 
master disk in a safe place and use the copy for your work. 

Buffer An area in the computer’s memory that MS-DOS uses to store data. 
Character A letter, number, or symbol that you type at your keyboard or see 
on your screen. 

Command A short program that tells MS-DOS how to do a specific task. 
Config.sys A special MS-DOS file that you use to configure the MS-DOS 
operating system. See also Autoexec.bat. 

CONTROL key Used in combination with other keys to give MS-DOS special 
commands such as "stop the last command” and "stop the display from 
scrolling." Press the conTRoL key at the same time as you press another key. 
CONTROL-c A control key combination that stops a command while it is 
running. See also CONTROL key. 
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CONTROL-S A control key sequence that stops or restarts the scrolling of the 
screen display. See also ConTROL key. 


Copy An MS-DOS commanp that copies one or more files on the same disk, or 
from one disk to another. 


Cursor The lighted shape on the screen that shows where the next character 
you type will appear. The cursor is usually a blinking line or small box. 


Default disk drive The drive where MS-DOS searches for any filenames 
that you may type. Unless you specify a different drive, MS-DOS looks for 
files in the default drive. The standard MS-DOS prompt contains the default 
drive letter. For example, if the prompt is A>, then "A" is the default drive. 


Del An MS-DOS command that tells MS-DOS to delete one or more files. A 
synonym for del is erase. 


Device A piece of hardware that performs a specific function. A printer is an 
example of a device. 


Device errors Errors that occur when one of your computer's devices, 
usually a disk drive or printer, is not ready or has a problem. When these errors 
occur, MS-DOS displays a device error message. 


Dir An MS-DOS command that means "directory." When you type the dir 
command, MS-DOS displays the contents of the disk in the default drive. The 
command dir b: displays the contents of the disk in drive B. 


Directory A table of contents for a disk. The directory contains the names of 
your files, the sizes of the files, and the dates they were created or last 
modified. 


Disk See Floppy disk; Hard disk. 

Disk drive A piece of hardware attached to your computer. Typically, a disk 
drive is either a floppy or hard disk drive. You insert floppy disks in floppy 
disk drives. Floppy disk drives are commonly referred to as the A drive and the 
B drive. Hard disks are usually built into the computer and are referred to as the 
C drive. Your computer manual should tell you how your drives are labeled. 
Disk operating system A group of programs that act as a translator 
between you and your computer. MS-DOS is a disk operating system. 
Diskcopy An MS-DOS command that copies disks. diskcopy formats a disk 
before copying files onto it. 


Terms 3 


Drive name Consists of a drive letter and a colon. A drive name tells MS- 
DOS which drive to search for the file. For example, the command type 
a.progress.rpt contains a drive name (a:) that tells MS-DOS to look on the disk 
in drive A for the file called progress.rpt. 


Editor A program that allows you to manipulate text and data on the 
computer. Editors allow you to move, add, and delete characters and lines, and 
to save files. The MS-DOS line editor is called Edlin. 


Edlin A line-oriented editor that comes with MS-DOS. See also Editor. 
ENTER key See RETURN Key. 
Erase A synonym for the MS-DOS del command. See also Del. 


Error messages Messages that appear on the screen after MS-DOS detects a 
problem while trying to process a command or program. See the MS-DOS 
User's Reference for the appropriate response to each error message. 


File A collection of related information. A file on a disk can be compared to a 
file folder in a desk drawer. For example, a file folder named friends might 
contain the names and addresses of your friends. A file on a disk could contain 
the same information, and could also be named friends. Programs are also 
stored in files. 


Filename A filename can be from one to eight characters in length and can 
have an extension of up to three characters separated from the filename by a 
period (.). An example of a complete filename is progress.rpt. Certain 
filenames are reserved by MS-DOS and should not be used when naming your 
files. These filenames are: aux, clock$, com, con, ipt, lst, nul, and prn. 


Filename extension An addition to a filename. Extensions begin with a 
period and contain from one to three characters. Most application programs 
supply their own extensions for files they create. For example, all cw-sasic files 
use a filename extension of .bas. See also Filename. 


Fixed disk See Hard disk. 


Floppy disk Used for storing programs and files. In this documentation, the 
term floppy disk includes 3.5-inch disks as well as 5.25-inch floppy disks. 
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Format An MS-DOS command that structures blank disks so that MS-DOS 
can store data on them. You must format every blank disk before it can be used 
with MS-DOS. Format also checks the disk for defective spots. 


GW-BASIC A general-purpose computer language. Often, BASIC (or GW- 
BASIC) is the first computer language that people learn. 


Hard disk Sometimes called a fixed disk, one that is built into the computer. 
A hard disk can store much more information than a floppy disk, and the 
computer can retrieve information from it faster. 


Hardware The equipment that makes up a computer system, not to 
beconfused with the programs, or software. 


Memory The active part of computer storage used when the computer runs a 
program or command. 


MS-DOS master disk The floppy disk (or disks) on which MS-DOS is 
distributed. You should always make a backup copy of the master disk (or 
disks) before you start using MS-DOS on a routine basis. 


Operating system A group of programs that translate your commands to the 
computer, helping you perform such tasks as creating files, running programs, 
and printing documents. See also Disk operating system. 

Print An MS-DOS command that prints files on your printer. 


Printer A printing device attached to your computer. It lets you print files so 
that you have a paper copy or printout. 

Program A set of instructions, written in computer language, that tells the 
computer how to perform some task. 


Prompt A symbol that usually consists of a default drive letter (usually A, B, 
or C) and a greater-than sign. An example of the MS-DOS prompt is B>. Other 
programs will use different prompts. For example, Edlin uses an asterisk (*) as 
a prompt. 

Rename An MS-DOS command that renames files. You can use the 
abbreviation ren in place of the full command name. 

RETURN key The key you usually press after entering data or text, or after you 
type an MS-DOS command. On some computers, the RETURN key is called the 
ENTER key. 

Scrolling The movement of text on your screen as it rolls up and off the top 
of the screen. 


Terms 5 


Software The programs, routines, or instructions that allow the computer to 
perform tasks. Some examples of software include: operating systems, word 
processing programs, and spreadsheet programs. 


Type An MS-DOS command that displays files on the monitor. 


Volume label An intemal name on a disk. You should put a volume label on 
each of your disks to help you identify them. 


Write-protect tab The small tab that covers the write-protect notch on a 
disk. On 5.25-inch disks, this tab is a removable piece of tape. On 3.5-inch 
disks, the built-in tab slides into position over the write-protect notch. After 
removing the tab, you can copy information onto the disk. See also Write- 
protected disk. 

Write-protected disk A floppy disk that you can examine information on 
but cannot change. These disks usually have a small tab covering a notch on the 
right edge of the disk. If a disk does not have a write-protect notch, you cannot 
change any information on the disk. 
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Backup copy 3.3 
Backup disk, definition T.1 
Blank disk 4.10 
Blank disk, formatting 4.8 
Booting MS-DOS. See Starting 
MS-DOS 
Buffer, definition 6.2 
Buffers command, config.sys 
description 6.2 
setting a value for 6.2 


Capital letters 1.3, 1.7, 2.6 
Changing a filename 4.5 
Command 

Backup T.1 

Copy 3.7, 4.3, T.1 

definition 1.6, T.1 

Del 4.4, T.2 

Dir 4.1, T.2 

Diskcopy 3.3, 4.10, T.1, T.2 
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Command (continued) 
Erase T.3 
Format 2.6, 3.5, 4.8 
Print 4.7, T.4 
Prompt, used in autoexec.bat 
6.4 
Rename 4.5 
stopping T.1 
Type 4.6, T.5 
Communications port 4.7 
Computer language, GW-BASIC 
T.4 
Computer memory T.4 
Computer system 2.5 
Config.sys command 
buffers 6.2 
files 6.2 
Config.sys file 
commands for 6.1 
creating with Edlin 6.2 
differences with autoexec.bat 
6.4 
further reference 6.3 
purpose 6.1 
restarting after changes 6.3 
sample file 6.2 
Configuration commands, 
config.sys 6.4 
Configuring MS-DOS. See 
Setting up MS-DOS 
CONTROL key 1.8, T.1 
CONTROL-ALT-DELETE 1.9, 3.2, 
4.9 
CONTROL-C 1.9, 5.4, 6.2, T.1 
CONTROL-S 1.8, 4.2, 4.6, T.2 
Copy command 3.7, 4.3, T.1, T.2 
Copying a disk 4.10 
Copying files 3.7, 4.3 
Correcting typing mistakes 3.2, 
5.4 
Creating a config.sys file 6.2 
Creating a file, Edlin 5.3 
Cursor 
moving 1.8 


Cursor (continued) 
MS-DOS 1.5 


Database program 6.2 
Date prompt 3.1 
Default directory 6.3, 6.4 
Default disk drive 1.5, 3.8, 4.3, 
4.4, 4.7, 6.3, 6.4 
Default drive T.2 
Del command 4.4, T.2 
Deleting a file 4.4 
Device error T.2 
Device names 2.7 
Differences between 
autoexec.bat and config.sys 
6.4 
Dir command 4.1, T.2 
Direction keys 1.8 
Directory 
contents 2.7 
default 6.3, 6.4 
definition 1.4, T.2 
displaying 2.7 
listing 4.1 
MS-DOS 2.7 
variations 2.8 
Disk 
3.5-inch 2.4 
backup T.1 
blank 4.10 
blank, formatting 4.8 
copying 4.10 
floppy 2.2 
formatting 2.6, 4.8 
hard 2.5 
label 4.10 
safe storage of 3.3 
volume label 1.4 
write-protected 2.3, T.5 
Disk commands 4.8 
Disk drive 
definition 1.4, T.2 


Disk drive (continued) 
floppy 1.4 
hard 1.4 
Disk operating system, MS-DOS 
T.2, T.4 
Disk protection T.5 
Diskcopy command 3.3, 4.10, 
T.1, T.2 
Diskcopy screen 3.4, 4.11 
Diskcopy.exe program 3.3 
Displaying a file 4.6 
DOWN ARROW key 1.8 
Drive letter 1.5 
Drive name 1.5 
definition T.3 
floppy disk T.2 
hard disk T.2 


Editing a file, Edlin 5.3 
Editor, definition T.3 
Edlin 
asterisk (*) prompt 6.2 
creating a config.sys file 6.2 
creating a file 5.4 
definition T.3 
description 5.3 
editing a file 5.4 
end command (e) 6.2 
exiting a file 5.4, 6.2 
insert command (i) 6.2 
inserting text 6.2 
line editor T.3 
line numbers 5.4 
prompt, asterisk (*) 5.4 
screen 5.4 
End command (e), Edlin 6.2 
ENTER key. See RETURN key 
Erase 4.5 
Erase command. See Del 
Erase. See also Del command 
Erasing a file 4.4 
Error message T.3 
Error, device T.2 
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Executable file, .exe 1.3 
Extension 
.bas 1.4, T.3 
.com 1.3 
.doc 1.4 
exe 1.3 
apt 1.3 
txt 1.4 
command 1.3 
executable 1.3 
filename 1.3, T.3 


File 
autoexec.bat 6.1, 6.3 
config.sys 6.1 
copying 4.3 
definition 1.2, T.3 
deleting 4.4 
displaying 4.6 
hidden 2.8 
naming 2.6 
printing 4.7 
renaming 4.3, 4.5 
File commands 4.1 
Filename 
allowed length T.3 
definition 1.3, 2.6, T.3 
extension 1.3, 2.6, T.3 
illegal 2.7 
invalid characters in 2.7 
length 1.3 
parts 2.6 
reserved T.3 
Files command, config.sys 
description 6.2 
setting a value for 6.2 
Fixed disk. See Hard disk 
Floppy disk 
copying 3.3 
description 2.2 
master 3.1 
storage capacity 2.2 
storing 2.2 
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Floppy disk (continued) 
storing safely 3.3 
use of T.3 
write-protected T.5 
Floppy disk drive 
autoexec.bat settings for 6.4 
drive name T.2 
Floppy disk drive, if you have 
only one 3.8 
Floppy disk do’s and don’ts 2.3 
Format command 2.6 
adding a label 4.9 
copying special files 4.9 
formatting a floppy disk 4.9 
formatting a hard disk 3.5 
options 4.9 
purpose 4.8, T.4 
waming 3.5, 4.10 
Format screen 4.9 
Formatting a disk 2.6, 4.8 
Further reference 
MS-DOS User's Reference 6.5 
Terms, MS-DOS 6.5 


Glossary T.1 
GW-BASIC 
definition T.4 


Hard disk 
backup copy of MS-DOS 3.5 
configuring 3.5 
copying master disk onto 3.7 
definition T.4 
description 2.5 
formatting 3.5 
storage capacity T.4 
Hard disk drive 
drive name T.2 
Hidden files 2.8 


Insert command (i), Edlin 6.2 
Internal name. See Volume label 
Invalid filenames 2.7 


Key 
BACKSPACE 3.2, 5.4 
CONTROL 1.8, T.1 
direction 
DOWN ARROW 1.8 
LEFT ARROW 1.8 
RIGHT ARROW 1.8 
UP ARROW 1.8 
RETURN 1.8, T.3, T.4 
SHIFT 1.8 
SPACEBAR 1.8 
Keyboard 
differences between keys 1.7 
keys 1.7 
special keys 1.8 


Label 2.2 

Labeling a disk 4.10 

LEFT ARROW key 1.8 

Letters, lowercase 1.3, 1.7, 2.6 
Letters, uppercase 1.3, 1.7, 2.6 
Line editor, Edlin 5.3, T.3 
Line numbers, Edlin 5.4 
Listing a directory 4.1 
Lowercase letters 1.3, 1.7, 2.6 


Master disk, MS-DOS 3.1, 3.3, 
T.4 
Memory 
buffer 6.2 
definition T.4 
Message, error T.3 
Microsoft Networks 6.2 
Microsoft Word 6.4 
Mistakes in typing, correcting 5.4 


More information about MS- 


DOS 

MS-DOS User’ s Reference 6.5 
Terms 6.5 

Moving the cursor 1.8 


MS-DOS 


a quick guide 6.5 
advanced topics 6.5 
config.sys commands 6.1 
configuring the operating 
system 6.1 
cursor 1.5 
default drive letter T.2 
further information 
MS-DOS User's Reference 
6.5 
Terms 6.5 
glossary T.1 
line editor, Edlin 5.3 
memory, buffer 6.2 
operating system, definition 
T.2, T.4 
prompt 1.5 
quitting 3.3 
setting up the operating system 
6.1 
special file 
autoexec.bat 6.1 
config.sys 6.1 
starting 3.1 
starting and restarting 1.9, 3.2 
terms 1.2, T.1 


MS-DOS command 


Backup T.1 

Buffers, config.sys 6.2 
Copy 3.7, 4.3, T.1 
definition 1.6, T.1 

Del 4.4, T.2 

Dir 4.1, T.2 

Diskcopy 3.3, T.1, T.2 
Erase T.3 

Files, config.sys 6.2 
Format 2.6, 3.5, 4.8 
Print 4.7, T.4 
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MS-DOS command (continued) 
Prompt, used in autoexec.bat 
6.4 
Rename 4.5 
Type 4.6, T.5 
MS-DOS directory 2.7 
MS-DOS User’ s Guide 
Summary 6.5 


Networks. See Microsoft 
Networks 
Notch, wnite-protect T.5 


Open files, need for 6.2 
Operating system, MS-DOS 
configuring 6.1 
descnption T.2, T.4 
setting up 6.1 
special file 
autoexec.bat 6.3 
special files 
autoexec.bat 6.1 
config.sys 6.1 


Port, communications 4.7 
Print command 4.7, T.4 
Printer, definition T.4 
Printing a file 4.7 
Program 
database 6.2 
Microsoft Networks 6.2 
Microsoft Word 6.4 
spreadsheet 6.2 
Program, definition 1.2, T.4 
Programming language, GW- 
BASIC T.4 
Prompt 
A> 3.2 
date 3.1 
default drive letter T.4 
definition T.4 
Edlin, asterisk (*) 5.4, 6.2 
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Prompt (continued) 
MS-DOS 1.5, T.4 
time 3.1 
Prompt command 
used in the autoexec.bat file 
6.4 
Protecting disks 2.3, T.5 


Quitting 
Edlin 5.4 
MS-DOS 3.3 


Re-booting MS-DOS. See 
Restarting MS-DOS 
References 
MS-DOS User's Reference 6.5 
Terms, MS-DOS 6.5 
Removing a file 4.4 
Rename command 
abbreviation T.4 
purpose 4.5, T.4 
Renaming a file 4.3, 4.5 
Reserved filenames T.3 
Restarting a config.sys 6.3 
Restarting MS-DOS 1.9, 3.2 
RETURN key 1.8, T.3, T.4 
RIGHT ARROW key 1.8 
Running an application program 
from autoexec.bat 6.4 
Running application programs 
5.1 


Sample config.sys file 6.2 
Screen 

Diskcopy 3.4, 4.11 

Edlin 5.4 

Format 4.9 

startup, MS-DOS 3.1 
Scrolling 

starting 1.8, 4.2, 4.6, T.2 

stopping 1.8, 4.2, 4.6, T.2 


Setting the date and time 3.2 
Setting up MS-DOS 6.1 
SHIFT key 1.8 
Shortcuts 
Rename command 4.5 
wildcard abbreviation T.1 
Single drive computers 3.8 
Software 
application T.5 
definition T.1 
operating system T.5 
program T.5 
spreadsheet T.5 
word processing T.5 
Software. See also Application 
programs 
SPACEBAR 1.8 
Special characters 2.7 
Special file 
autoexec.bat 6.1, 6.3 
config.sys 6.1 
differences between config.sys 
and autoexec.bat 6.4 
Special file, MS-DOS 4.8 
Special keys 1.8 
Spreadsheet program 6.2 
Starting an application program 
5.1 
Starting MS-DOS 1.9, 3.1, 3.2 
Startup screen 3.1 
Stopping a command 1.9 
Stopping scrolling 1.9 
Storage area 
buffer 6.2 
computer. See Memory 
Summary of the MS-DOS User's 
Guide 6.5 
Synonym 
Del 4.5 
Erase 4.5 
System prompt, MS-DOS 1.5 


Tab, write-protect T.5 

Task 1.6 

Terms, MS-DOS 1.2, T.1 

Text editor, Edlin 5.3 

Text file 4.6 

Time prompt 3.1 

Type command 4.6, T.5 

Typing mistakes, correcting 3.2, 
5.4 


UP ARROW key 1.8 
Uppercase letters 1.3, 1.7, 2.6 


Valid filename characters 2.7 
Volume label 1.4, 3.6, 4.9, T.5 


Wildcard characters, asterisk (*) 
T.1 

Word. See Microsoft Word 

Write-protect notch 2.4, T.5 

Write-protect tab 2.3, T.5 

Wnite-protected disk T.5 
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Introduction 


What you see before you is a resource manual. It is unlikely that you will ever 
sit down to read it cover to cover. Rather, you will probably pick it up when 
you are looking for a specific piece of information. The MS-DOS User's 
Reference was designed with that in mind. 


This manual is written for the person who has some experience with personal 
computers. To best use this manual, you should be familiar with the 
introductory information in the MS-DOS User's Guide and know how to start 
MS-DOS8®, how to copy, delete, and rename files, how to make copies of 
disks, and how to run applications. 

Also, you should have already made a backup copy of your MS-DOS master 


disk and stored the original in a safe place. If you haven’t done so, refer to the 
MS-DOS User's Guide to learn how to make a backup copy of your disk. 
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What is MS-DOS? 


The Microsoft® MS-DOS operating system is like a translator between you and 
your computer. The programs in this operating system allow you communicate 
with your computer, your disk drives, and your printer, letting you use these 
resources to your advantage. 


MS-DOS also helps you to manage programs and data. Once you have loaded 
MS-DOS into your computer’s memory, you can compose letters and reports, 
run programs and languages such as Microsoft GW-BASIC®, and use devices 
such as printers and disk drives. 


MS-DOS Version 3.3 


This version of MS-DOS has several new features, including 


e Perfomance improvements. Several internal enhancements and a new 
command, fastopen, improve MS-DOS performance, especially with 
applications that use many files. 


e Support for 1.44 megabyte, 3-1/2 inch disks. 


e Support for four serial (COM) ports. Previous versions of MS-DOS 
supported two. 


e Enhancements to config.sys commands including buffers, stacks, device. 
MS-DOS 3.3 also includes a new config.sys command, country. 


e Ability to use partitions larger than 32 megabytes. You can create 
extended DOS partitions for disks larger than 32 megabytes with fdisk. 


e Improved national language support. MS-DOS 3.3 offers the ability to 
select alternate language-specific character sets (called code pages) 
instead of the standard U.S. character set. Three new commands—chep, 
nisfunc, and select, and several enhanced MS-DOS commands, 
including keyb and mode support code page selection. In addition the 
config.sys command, country, and two new installable device drivers 
allow you to select language-specific code pages. 


e Enhanced batch processing capabilities. 


ə Ability to make a system disk formatted by an earlier version of MS-DOS 
bootable with MS-DOS 3.3. This is possible because MS-DOS 3.3 
allows the io.sys system file to be noncontiguous on the disk. 
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è Various enhancements to existing commands, including 


append format mode 
attrib graphics restore 
backup keyb time 
date 


Notational Conventions 


Throughout this manual, the following conventions are used to distinguish 
elements of text: 


bold Used for commands, options, switches, and literal portions 
of syntax that must appear exactly as shown 


italic Used for filenames, variables, and placeholders that 
represent the type of text to be entered by the user 


monospace Used for sample command lines, program code and 
examples, and sample sessions 


SMALL CAPS Used for keys, key sequences, and acronyms 


How to Use This Manual 


The following table is a quick overview of the topics covered in this manual. 
For more specific topics, you may have to check the table of contents or the 
index. 


Turn to If you need to know 

Chapter 1 About multilevel directories 
About paths 

Chapter 2 About MS-DOS commands 

Chapter 3 How to use MS-DOS commands 

Chapter 4 How to make a batch file 


How to use commands 
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Chapter 5 About MS-DOS editing keys 
Chapter 6 How to use Edlin, the line editor 

How to use Edlin commands 
Chapter 7 How to create executable files with link 
Chapter 8 How to debug files with debug 
Appendix A What to do if you have only one disk drive 
Appendix B How to configure your system 
Appendix C About ANsI escape sequences 

About installing device drivers 
Appendix D How to configure your hard disk 
Appendix E About code pages 


How to set up your personal computer and peripheral 
devices with code page support 


Appendix F Error messages and what they mean 
MS-DOS prompts and what they mean 


These other manuals will also be of interest to you: 
MS-DOS User's Guide Introduces you to the basics of MS-DOS 


MS-DOS Programmer's Provides detailed information necessary 
Reference for programming with MS-DOS 


Now that you’ve seen a brief summary of what topics this manual covers, 
you're ready to start with Chapter 1, "More About Files and Directories.” 
There you'll learn about some of the more advanced features of MS-DOS. 


1 More About Files 
and Directories 


In this chapter you will learn about 


e Protecting and keeping track of your files 
e Working with multilevel directories 


e Using wildcards 


Before You Start 


Before you read this chapter, you should already know how to start MS-DOS, 
format and make backup copies of disks, copy and delete files, and run 
programs. If you are unfamiliar with how to do any of these actions, just refer 
to the MS-DOS User's Guide for more information. “4 
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File Protection 


The MS-DOS operating system is a powerful and useful tool for processing 
personal and business information. As with any computer, this information 
must be protected, since errors may occur and information may be misused. So 
if you are doing work that cannot be replaced or that requires a lot of security, 
you should protect your programs. 


You can take simple but effective measures like putting your disks away when 
you're not using them, or covering the write-protect notch on your program 
disks. Another way to protect your programs is by installing your equipment in 
a secure office or work area. Also, if your disks contain valuable information, 
you should make backup copies of them on a regular basis. For more 
information on backing up disks, see the backup and restore commands in 
Chapter 3, "MS-DOS Commands.” 


How MS-DOS Keeps Track of Your Files 


As you learned in the MS-DOS User's Guide, MS-DOS stores files in 
directories. In addition to directories, it uses an area on a disk called the File 
Allocation Table. When you format a disk with the format command, MS- 
DOS copies this table onto the disk and creates an empty directory, called the 
root directory. On each of your disks, the directories store the files, and the 
File Allocation Table keeps track of their locations. The table also allocates the 
free space on your disks so that you have enough room to create new files. 
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These two system areas, the directories and the File Allocation Table, enable 
MS-DOS to recognize and organize the files on your disks. To check these 
areas on a disk for consistency and errors you should use the MS-DOS chkdsk 
command. 

For example, to check the disk in drive A, type the chkdsk command, followed 
by a: 

In response, MS-DOS displays a status report and any errors it has found, such 
as files that show a nonzero size in the directory but that really have no data in 
them. 

For an example of such a display and for more information on chkdsk, see the 
description of the chkdsk command in Chapter 3, "MS-DOS Commands.” 


Multilevel Directories 


When there is more than one user on your computer, or when you are working 
on several different projects, the number of files in the directory can become 
large and unwieldy. To deal with this large number of files, you may want to 
keep your files separate from a coworker’s, or organize your programs into 
convenient categories. 
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In an office, you can separate and organize files that belong to different people 
or that relate to specific projects by putting them in different file cabinets. For 
example, you might put your accounting programs in one file cabinet and your 
letters in another. You can do the same thing with MS-DOS by putting your 
files into different directories. 

Directories let you group your files in convenient categories. These directories, 
in tum, may contain other directories (referred to as subdirectories). This 
organized file structure is called a multilevel or hierarchical directory system. 


Note The maximum number of files or directories that the root directory may 
contain varies, depending on the type of disk and disk drive you are using. 
Usually, the maximum number is 112 for a double-sided, double-density, 5.25- 
inch floppy disk. The maximum number of entries in the root directory of a 
1.44 megabyte, 3.25-inch floppy disk is 224. This maximum capacity for a root 
directory may vary depending upon how the disk is formatted. The number of 
subdirectories on a disk is not restricted. 
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The first level in a multilevel directory is the root directory, which is created 
automatically when you format a disk and start putting files on it. Within the 
root directory, you can create additional directories and subdirectories. 


As you create new directories for groups of files, or for other people using the 
computer, the directory system grows. And within each new directory you can 
add new files or create new subdirectories. 


You can move around in the multilevel system by starting at the root and 
“traveling” through intermediate subdirectories to find a specific file. 
Conversely, you can start anywhere within the file system and travel toward the 
root. Or you can go directly to any directory without traveling through 
intermediate levels. 


The directory that you are in is called the working directory. The filenames and 
commands discussed in this chapter relate to your working directory and do not 
apply to any other directories in the structure. When you start your computer, 
you start out in the working directory. Similarly, when you create a file, you 
create it in the working directory. 

Because you can put files in different directories, you and your coworkers can 


have files with the same names, but with unrelated content. The following 
figure illustrates a typical multilevel directory structure: 
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Root directory 








In this example, five subdirectories of the root directory have been created. 
These subdirectories are 


A directory of external commands, named bin. 


A user directory containing separate subdirectories for all users of the 
system. 


A directory containing accounting information, named accounts. 
A directory of programs, named programs. 
A directory of text files, named memos. 


As you can see, Pete, Emily, and Isabel each have their own directories, which 

are subdirectories of the user directory. Emily has a subdirectory named forms, 
and both Emily and Isabel have sales.may files in their directories, even though 
Isabel’s sales.may file is unrelated to Emily’s. 
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This organization of files and directories is not important if you work only with 
files in your own directory, but if you work with someone else, or on several 
projects at once, the multilevel directory system becomes handy. For example, 
you could get a list of the files in Emily’s forms directory by typing the 
following command: 


dir \user\emily\forms 


Note that a backslash (\) separates directories from other directories and files. 
In the previous example, the first backslash includes the root directory. The use 
of the backslash alone indicates the root directory. For example, the following 
command displays a list of the files in the root directory: 


dir \ 

To find out what files Isabel has in her directory, you would type the following 
command: 

dir \user\isabel 


This command tells MS-DOS to travel from the root directory to the user 
directory to the isabel directory, and to then display all filenames in the isabel 
directory. 


Paths and Pathnames 


When you use multilevel directories, you must tell MS-DOS where the files are 
located in the directory system. Both Isabel and Emily, for example, have files 
named sales.may, so each would have to tell MS-DOS in which directory her 
file resides when she wants to use it. This is done by giving MS-DOS a 
pathname to the file. 


A pathname is a sequence of directory names followed by a filename. Each 
directory name is separated from the previous one by a backslash (\). A path 
differs from a pathname in that it does not include a filename. 


The general format of a pathname is as follows: 


[\directoryname] [\directoryname...] \filename 
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A pathname may contain any number of directory names up to a total length of 
63 characters. If a pathname begins with a backslash, MS-DOS searches for the 
file beginning at the root of the directory system. Otherwise, it begins at the 
working directory and searches along the path from there. Here are two 
examples: 


The pathname of Emily’s sales.may file is 
\user\emily\sales.may 

The pathname of Isabel’s sales.may file is 
\user\isabel\sales.may 


When you are in your working directory, you may use a filename and its 
corresponding pathname interchangeably. Some sample names are: 


\ The root directory. 

\programs A directory under the root directory that 
contains program files. 

\user\tsabel\forms\1040 A typical full pathname. This one is for a 
file named 1040 in the forms directory, 
which belongs to Isabel. 

sales.may A file in the working directory. 


A parent directory is any directory that contains subdirectories. MS-DOS 
provides special shorthand notations for the working directory and the parent of 
the working directory, and automatically creates these two entries whenever 
you create a directory: 
MS-DOS uses the shorthand name "." to indicate the name of 
the working directory in all multilevel directory listings. 


These two dots are the short-hand name "..” for the working 
directory’s parent directory (one level up). If you type the dir 
command followed by two dots, MS-DOS lists the files in the 
parent directory of your working directory. 

If you type the following command MS-DOS lists the files in 
the parent’s parent directory: 


dir ..\.. 
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Wildcards 


If you are using multilevel directories, you will find it easier to search for files 
on your disks if you use two special characters, called wildcards. The wildcard 
characters are the asterisk (*) and the question mark (?). They are useful in 
MS-DOS command lines because they give you flexibility when you are 
specifying paths and files. 


The ? Wildcard 


A question mark (?) in a filename or filename extension means that any 
character can occupy that position. The following command, for example, lists 
all filenames on the default drive that begin with the characters memo, that have 
any character in the next position, that end with the characters aug, and that 
have an extension of .txt: 


dir memo?aug.txt 


Here are some examples of files that might be listed by the preceding 
command: 


MEMO2AUG. TXT 
MEMO9AUG. TXT 
MEMOBAUG. TXT 


The * Wildcard 


An asterisk (*) used in a filename or filename extension means that any 
character can occupy that position or any of the remaining positions in the 
filename or extension. For example, the following command lists all the 
directory entries on the default drive with filenames that begin with the 
characters memo and that have an extension of .txt: 


dir memo*.txt 
Here are some examples of files that might be listed by this dir command: 


MEMO2AUG. TXT 
MEMOSAUG. TXT 
MEMOBAUG. TXT 
MEMOJULY. TXT 
MEMOJUNE. TXT 
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MS-DOS ignores any filename characters that follow the asterisk wildcard, up 
to the period that separates the filename from its extension. For example, the 
command dir *].mem would list all the files in the directory with the extension 
mem, not just those files whose names end with the number /. 


Important The wildcard abbreviation *.* refers to all files in the directory. 
This feature can be both powerful and destructive when used with MS-DOS 
commands. For example, the del command followed by the wildcard 
abbreviation *.* deletes all files on the default drive, regardless of filename or 
extension. 


Examples: 


Suppose you want to find a certain accounting file but can’t remember its exact 
name. What you can do is list the directory entries for all files named accounts 
in the default directory of drive A (regardless of their filename extensions). To 
do this quickly, you could just type the following command: 


dir a:accounts.* 


Similarly, to list the directory entries for all files with .txt extensions or in a 
directory called reports (regardless of their filenames) on the disk in drive B, 
type the following command: 


dir b:\reports\*.txt 


This command is useful if your text files have .txt extensions. For example, by 
using the dir command with wildcard characters, you could get a listing of all 
your text files—even if you don’t remember their filenames. For more 
information on the dir command, refer to Chapter 3, "MS-DOS Commands." 


Using Directories 


The following sections describe how to display, change, and delete any 
directory. You will also learn how to create directories and subdirectories. 
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How to Create a Directory 


To create a subdirectory in your working directory, use the mkdir (make 
directory) command. For example, to create a new directory named user under 
your working directory, simply type the following command: 


mkdir user 


After MS-DOS runs this command, a new directory will exist under your 
working directory. You can also make directories anywhere in the directory 
structure by specifying mkdir followed by a path. MS-DOS automatically 
creates the "." and ".." entries in the new directory. 

To create files in the new directory, you can use the MS-DOS line editor, 
Edlin. Chapter 6, "The Line Editor (Edlin)," describes how to use Edlin to 
create and save files. You can also create and save files if you have a word 
processing program such as Microsoft Word. 


How to Change Your Working Directory 


With MS-DOS it is easy to change from your working directory to a different 
directory: you simply type the chdir (change directory) command followed by 
a path. For example, to change the working directory to \user, you simply type 
the following: 


chdir \user 


You can also specify any path after the command so that you can travel around 
the directory structure. The following command, for example, puts you in the 
parent directory of your working directory: 


chdir .. 


How to Display Your Working Directory 


All commands are executed while you are in your working directory. You can 
find out the name of the directory you are in by typing the MS-DOS chdir 
command with no path. For example, if your working directory is \user\pete, 
when you type chdir and press the RETURN key, you will see the following: 


A: \USER\PETE 


This message shows your working drive, A, plus your working directory, 
\user\pete. 
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Shortcut You can also type the letters cd for the chdir command to save 
time. For example, the following commands are the same: 


cd \user\pete 
chdir \user\pete 


If you want to see the contents of the \user\pete directory, you can use the MS- 
DOS dir command. The subdirectory might look like this: 


Volume in drive A has no ID 
Directory of A:\USER\PETE 


<Dir> 08-09-87 10:09a 
axe <Dir> 08-09-87 10:09a 
TEXT <Dir> 08-09-87 10:09a 
FILE1 TXT 5243 08-04-87 9:30a 


File(s) 836320 bytes free 


Note that MS-DOS lists both files and directories in this output. As you can see 
from the display, Pete has a subdirectory named text; the "." refers to the 

working directory \user\pete; the ".." is short for the parent directory \user, and 
filel txt is a file in the \user\pete directory. All these directories and files are on 


the disk in drive A. 


Note Because files and directories are listed together, you cannot give a 
subdirectory the same name as a file in that directory. For instance, if you 
already have a path \user\pete, where pete is a subdirectory, you cannot create a 
file named pete in the \user directory. 


How to Delete a Directory 


If you create a directory and decide later that you don’t want it any more, you 
can delete it with the MS-DOS rmdir (remove directory) command. 


The rmdir command lets you delete any directory by specifying its path, but 
the directory must be empty except for the "." and ".." entries. This prevents 


you from accidentally deleting files and directories. 
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To remove all the files in a directory (except for the "." and ".." entries) type 
del followed by the path of the directory. For example, to delete all files in the 
\user\emily directory, type the following command: 


del \user\emily 

MS-DOS prompts you with the following message: 

Are you sure (Y/N)? 

If you really want to delete all the files in the directory, type Y (for Yes). If not, 
type N (for No) to stop the command. 

Now you can use the rmdir command to delete the \user\emily directory by 
typing the following command: 

rmdir \user\emily 


Shortcut To save time you can also use the letters rd for the rmdir 
command. 


How to Rename a Directory 


There is no command to rename a directory in MS-DOS. You can, however, 
rename a directory that has no subdirectories. Suppose, for example, you want 
to rename the \user\pete directory and call it \user\emily. To do this you would 
follow these steps (remember to press the RETURN key after each step): 


1. To create the new directory, type 
mkdir \user\emily 
2. Then to copy the files from the old directory to the new directory, type 
copy \user\pete\*.* \user\emily 
3. Now to delete the contents of the old directory, type 
del \user\pete\*.* 
(Type Y in response to the prompt "Are you sure?") 
4. Finally, to remove the old directory, type 


rmdir \user\pete 
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In this chapter, you’ve learned more about files and directories, about wildcards 
and how to use them, and about some basic MS-DOS commands that help you 
work with files and directories. In the next chapter, you’ll learn about the two 
kinds of commands, and about using redirection symbols. 


2 About Commands 


In this chapter, you will learn about 
e __ Internal and external MS-DOS commands 
e Redirecting input and output 


e Command grouping symbols 


Types of MS-DOS Commands 


There are two types of MS-DOS commands: 
Internal commands 
External commands 


Internal commands are the simplest, most commonly used commands. When 
you list the directory on your MS-DOS disk, you cannot see these commands 
because they are part of a file named command.com. When you type internal 
commands, MS-DOS performs them immediately. This is because they were 
loaded into your computer’s memory when you started MS-DOS. Following is 
a list of the MS-DOS internal commands: 


break del mkdir set 
chep dir path shift 
chdir echo pause time 
cls exit prompt type 
copy for rem ver 
ctty goto ren verify 


date if rmdir vol 
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Some internal commands can use paths and pathnames. Specifically, four 
commands — copy, dir, del, and type—have greater flexibility when you 
specify a pathname after the command. 


The formats of these commands are as follows: 
e copy pathname pathname 


If the second pathname is a directory (a path), MS-DOS copies all the files 
you specify in the first pathname into that directory, as in the following 
example: 


copy \user\pete\*.* sales 
e = del pathname 


If the pathname is a directory (a path), all the files in that directory are 
deleted. If you try to delete a path, MS-DOS displays the prompt "Are 
you sure (Y/N)?". Type Y (for Yes) to complete the command, or N (for 
No) to stop the command. Example: 


del \user\pete 

e = dir path 
The following command displays the directory for a specific path: 
dir \user\pete 

e type pathname 


You must specify a pathname (or filename) for this command. MS-DOS 
then displays this file on your screen in response to the type command. 
Example: 


type \user\emily\report.nov 


Any filename with an extension of .com, .exe, or .bat is considered an external 
command. For example, files such as format.exe and diskcopy.exe are external 
commands. And because all external commands are also files, you can create 
new commands and add them to MS-DOS. Programs that you create with most 
languages (including assembly language) will be .exe (executable) files. Note, 
however, that when you use an external command, you do not need to type its 
filename extension. 
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Note If you have more than one external command with the same name, MS- 
DOS will run only one of them, according to the following order of precedence: 
.com, .exe, .bat. 


To illustrate this precedence, suppose your disk contains the files format.exe 
and format.bat. If you were to type the external command format, MS-DOS 
would always run the program format.exe first, and not run the format.bat file 
at all. 


The following external commands are described in Chapter 3, "MS-DOS 
Commands": 


append fdisk recover 
assign find replace 
attrib format restore 
backup graftabl select 
chkdsk graphics share 
command join sort 
comp keyb subst 
diskcomp label sys 
diskcopy mode tree 
exe2bin more xcopy 
fastopen nisfunc 

fc print 


Before MS-DOS can run external commands, it must read them into memory 
from the disk. When you give an external command, MS-DOS immediately 
checks your working directory to find that command. If it isn’t there, you must 
tell MS-DOS which directory the external command is in. You do this with the 
path command. 


When you are working with more than one directory, you may find it more 
convenient to put all the MS-DOS external commands in one directory. Then, 
when it needs them, MS-DOS can quickly find the external commands at one 
location. 


Suppose, for example, that you are in a working directory named \user\prog 
and that the MS-DOS extemal commands are in Win. To find the format 
command, you must tell MS-DOS to choose the \bin path, as in the following 
command, which tells MS-DOS to search in your working directory and in the 
\bin directory for all commands: 


path \bin 


You need only specify this path once during each computer session. Also, if 
you want to know what the current path is, you can simply type the path 
command by itself. In response, MS-DOS then displays the working path on 
the screen. 
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You can automatically set your path when you start MS-DOS by including the 
path command in a file called autoexec.bat. For more information on the 
autoexec.bat file, refer to Chapter 4, "Batch Processing.” 


Redirecting Command Input and Output 


Usually, MS-DOS receives input from the keyboard and sends its output to the 
screen. You can, however, redirect this flow of command input and output. 
For instance, you may want input to come from a file instead of from the 
keyboard, and you may want output from a command to go to a file or 
lineprinter instead of to the screen. With redirection symbols, you can also 
create pipes that let the output from one command become the input for another 
command. 


How to Redirect Your Output 


By default, most commands send output to your screen. If you want to change 
this and send the output to a file, you just use a greater-than sign (>) in your 
command. For example, the following command displays on the screen a 
directory listing of the disk in the default drive: 


dir 
The dir command can send this output to a file named contents if you type the 
following: 


dir > contents 


If the contents file doesn’t exist, MS-DOS creates it and stores your directory 
listing there. If contents does exist, MS-DOS replaces what is in the file with 
the new data. 

If you want to append your directory or add one file to another (instead of 
replacing the entire file), you can use two greater-than signs (>>) to tell MS- 
DOS to append the output of the command (such as a directory listing) to the 
end of a specified file. For example, the following command appends your 
directory listing to an existing file named contents: 


dir >> contents 


If contents doesn't exist, MS-DOS creates it. 
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How to Redirect Input 


Often, it’s useful to have input for a command come from a file instead of from 
the keyboard. This is possible in MS-DOS by using a less-than sign (<) in your 
command. For example, the following command sorts the file names and sends 
the sorted output to a file called namelist: 


sort < names > namelist 


Filters and Pipes 


A filter is a command that reads your input, transforms it in some way, and 
then outputs it to your screen. In this manner, the input is "filtered" by the 
program. 


MS-DOS filters include: find, more, and sort. Their functions are as follows: 


find Searches for text in a file 
more Displays the contents of a file one screenful at a time 
sort Alphabetically sorts the contents of a file 


You can redirect the output from a filter into a file, or use it as input for another 
filter by using pipes. The following section explains how filters are piped 
together. 


Command Pipes 


If you want to use the output from one command as the input for another, you 
can pipe the commands to MS-DOS. Piping is done by separating commands 
with the pipe symbol, which is a vertical bar (i). The following command, for 
example, displays an alphabetically sorted listing of your directory on the 
screen: 


dir ! sort 


The pipe sends all output generated by the dir command (on the left side of the 
bar) as input to the sort command (on the right side of the bar). 
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You can also use piping with redirection symbols if you want to send the output 
to a file. For example, the following command creates a file named direct.lst 
on your default drive: 


dir ! sort > direct.lst 


The direct.lst file now contains a sorted listing of the directory on the default 
drive. 

You can also specify a drive other than the default drive. Suppose, for example, 
you want to send the sorted data to a file named direct.lst on drive B. To do this 
you could simply type the following: 


dir | sort > b:direct.lst 


You can use more than one pipe on a command line. The following command, 
for instance, sorts your directory, shows it to you one screen at a time, and puts 
--More-- at the bottom of your screen when there is more output to be seen: 


dir ! sort | more 


Since commands and filters can be piped together in many different ways, you 
will find many uses for them. 


In this chapter, you’ve learned about internal and external MS-DOS commands 
and how to redirect their input and output. The next chapter lists each of these 
commands in alphabetical order along with their syntax and comments about 
their use. 


3 MS-DOS Commands 


This chapter provides details about all of the MS-DOS commands (the 
commands are listed in alphabetical order). In this chapter, you will learn 


Which symbols are used to show internal commands, external commands, 
and commands that won't work over a network 


The structure of the command page 
What command options are 


Which notational conventions are used in this chapter 
How to use each MS-DOS command 
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External and internal commands are shown by the following symbols: 


[I] This shows that the command is intemal. 


[E] This shows that the command is external. 


Some MS-DOS commands do not work over a computer network. If you try to 
use these commands over a network, MS-DOS displays the error message 
"Cannot command to a network device," where command is the name of the 
command you typed. 


If the command does not work over a network (on a shared or remote device), 
you will see this symbol in the command description: 


&) 


For various reasons, the following commands do not work over a network (see 
the descriptions of the individual commands for more detailed explanations): 


chkdsk join 
diskcomp label 
diskcopy recover 
fdisk subst 
format sys 


The following page shows a sample command page. Each command described 
in this chapter follows this sample command format 
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Sample Command 
Purpose: 


The "Purpose" section tells you what the command is used for. 


Syntax: 


commandname [options] 

where: 

commandname is the name of an MS-DOS command. 

options may include drive., path, filename, pathname, switch, and/or argument. 


Comments: 


The "Comments section" describes the command how to use it. It also explains 
why the command is useful and explores each of the command’s options. 


Notes: 


The "Notes section" discusses important points related to the command; for 
instance, 


e You can specify a drive and/or path before any command, unless 
otherwise specified in the notes section. 


Examples: 


The "Example section" gives one or more examples that illustrate how to use 
the command. 
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Command Options 


Command options give MS-DOS extra information about a command. If you 
omit options, MS-DOS either prompts you to supply them or it uses a default 
value. Refer to individual command descriptions in this chapter for default 


values. 


MS-DOS commands use the following syntax: 


command [options] 
Command is an MS-DOS command, and [options] is one or more of the 


following: 


Option 
drive: 


path 


filename 


pathname 


switches 
arguments 


string 


Description 


Refers to a disk drive name. You need to specify a drive name 
only if you are using a file that is not on the default drive. 


Information transferred between two disks is sent from a source 
drive to a target drive. 


Refers to a directory name with the following syntax: 
[Mdirectory][directory...]\directory 


Refers to a file, and includes any filename extension. The 
filename option does not refer to a device or drive name. 


A path plus a filename is called a pathname. A pathname uses 
the following syntax: 

{directory](directory...])ilename 

Control MS-DOS commands. Switches begin with a slash; for 
example, /p. 

Provide more information to MS-DOS commands. You usually 
choose between arguments; for example: on or off. 


Many commands work with strings of text. A string is a group 
of characters that can include letters, numbers, spaces, and any 
other characters. Searching for a particular word in a file is a 
common use of a string. 
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More About Options 


The MS-DOS User's Reference uses the following conventions for command 


options: 
Convention 
italics 
[brackets] 


... (ellipsis) 


separators 


Usage 

You must supply the text for any of the variable items 
shown in italics. For example, when filename appears, you 
should type the name of your file. 


Items in brackets are optional. To include optional 
information, type only the information within the brackets. 
Do not type the brackets themselves. 


An ellipsis (...) means that you can repeat an item as many 
times as necessary. 


Unless otherwise specified, you must use spaces to separate 
commands from their options; for example, 


rename dull.doc sharpe.doc 


With some commands, you may use a semicolon (;), an 
equal sign (=), or a tab to separate MS-DOS commands 
from their options. These characters are also known as 
separators. 

In this manual, spaces separate commands from their 
options. 


The following three pages briefly describe each MS-DOS command. 
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MS-DOS Commands 


The following MS-DOS commands are described in this chapter. Note that 
synonyms for commands are in parentheses. 


Note If you have only one floppy disk drive, refer to Appendix A, 
"Instructions for Users with Single Floppy Disk Drive Systems,” before 
running any of the following commands. 


append 
assign 
attrib 
backup 
break 
chcp 


chdir 
chkdsk 
cls 
command 
comp 
copy 
ctty 

date 

del 

dir 
diskcomp 
diskcopy 
exe2bin 


Sets a search path for data files. 

Assigns a drive letter to a different drive. 

Sets or displays file attributes. 

Backs up one or more files from one disk to another. 
Sets CONTROL-c check. 


Displays or changes the current code page for the command 
processor command.com. 


Changes directories or prints the working directory (cd). 
Scans the disk in the specified drive and checks for errors. 
Clears the screen. 

Starts the command processor. 

Compares the contents of two sets of files 

Copies the specified file(s). 

Lets you change the device from which you issue commands. 
Displays and sets the date. 

Deletes the specified file(s) (erase). 

Lists the files in a directory. 

Compares disks. 

Copies disks. 

Converts executable (.exe) files to binary format. 


exit 
fastopen 


fc 

fdisk 
find 
format 
graftabl 
graphics 
join 
keyb 
label 
mkdir 
mode 
more 
nisfunc 
path 
print 
prompt 
recover 
ren 
replace 
restore 
rmdir 
select 


set 


share 
sort 
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Exits the command processor and returns to the previous level. 


Decreases the amount of time needed to open frequently-used 
files and directories. 


Compares files and displays differences between them. 
Configures hard disks for MS-DOS. 
Searches for a specific string of text. 
Formats a disk to receive MS-DOS files. 
Loads a table of graphics characters. 
Prepares MS-DOS for printing graphics. 
Joins a disk drive to a path. 

Loads a keyboard program. 

Labels disks. 

Makes a directory (md). 

Sets operation modes for devices. 
Displays output one screen at a time. 
Loads country-specific information. 

Sets a command search path. 

Prints files. 

Changes the MS-DOS command prompt. 
Recovers a bad disk or file. 

Renames first file as second file (rename). 
Replaces previous versions of files. 
Restores backed up files. 

Removes a directory (rd). 


Installs MS-DOS on a new floppy disk with desired country- 
specific information and keyboard layout. 


Sets one string value to another in the environment, or displays 
the environment. 


Installs file sharing and locking. 


Sorts data forward or backward. 
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subst 
sys 


time 
tree 
type 
ver 
verify 
vol 


xcopy 


Substitutes a string for a path. 

Transfers MS-DOS system files from one drive to the drive 
specified. 

Displays and sets the time. 

Displays directory and file names. 

Displays the contents of a file. 

Prints the MS-DOS version number. 

Verifies all writes to a disk. 

Displays the volume label. 

Copies files and subdirectories. 


These commands are described in detail in the following pages. 
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Append 


Purpose: 


Sets a search path for data files. 
Syntax: 


First use only: 
append [/x] [/e] 
To specify directories to be searched: 
append [drive:]path[;[drive:][path]...] 
To delete appended paths: 
append; 
where: 
path is the directory that MS-DOS searches for a data file. 


Comments: 


The append command allows you to specify a search path for data files. 


The append command accepts switches only the first time the command is 
invoked. Append accepts these switches: 


Switch Purpose 

Ix Extends the search path for data files. MS-DOS first searches the 
current directory for data files. If MS-DOS doesn’t find the needed 
data files there, it searches the first directory in the append search 
path. If the files are still not found, MS-DOS continues to the second 
appended dierctory, and so on. MS-DOS will not search subsequent 
directories once the data files are located. 

le Causes appended directories to be stored in the MS-DOS 
environment. 


You can specify more than one path to search by separating each with a 
semicolon (;). If you type the append command with the path option a second 
time, MS-DOS discards the old search path and uses the new one. 


If you don’t use options with the append command, MS-DOS displays the 
current data path. 


And if you use the following command, MS-DOS sets the NUL data path: 
append ; 
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This means that MS-DOS searches only the working directory for data files. 


Notes: 


e You can use the append command across a network to locate remote data 
files. 


e Ifyou are using the MS-DOS assign command, you must use the append 
command before assign. 


e Ifyou want to set a search path for external commands, see the path 
command in this chapter. 


e Append searches the data path for all files, regardless of their file 
extensions, only with the following MS-DOS system calls: 


Code Function 

OFH Open File (FCB) 

23H Get (FCB) File Size 

3DH Open Handle 

11H FCB search first (with /x switch only) 
4EH Handle find first (with /x switch only) 
4BH Exec (with /x switch only) 


Examples: 


Suppose you want to access data files in a directory called letters on drive B, 
and in a directory called reports on drive A. To do this, use the following 
command: 

append b:\letters;a:\reports 

Suppose you wanted to use the /x extension switch so that append first 
searched the current directory for data files before using the appended search 
paths. To do this, you would type this command before you typed any other 
append command: 

append /x 


If you then typed the following command, MS-DOS would first search your 
current directory for data files. If MS-DOS didn’t find the data files in your 
current directory, it would search the directory called Vieworder on drive C. 
And, if the files were not there, MS-DOS would search Wakorder on drive C. 


append c:\neworder;c: \bakorder 
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Assign 

Purpose: 

Assigns a drive letter to a different drive. 
Syntax: 


assign [x[=]y[ ...] J 
where: 


x is the drive that MS-DOS currently reads and writes to. 
y is the drive that you want MS-DOS to read and write to. 


Comments: 


The assign command lets you read and write files on drives other than A and B 
for applications that use only those two drives. You cannot assign a drive being 
used by another program, and you cannot assign an undefined drive. Do not 
type a colon after the drive letters x and y. 


Notes: 


e To ensure compatibility with future versions of MS-DOS you should use 
the subst command instead of assign. The following commands, 
therefore, are equivalent: 


assign a = c 
subst a: c:\ 


e Since the assign command disguises the true device type, you should not 
use assign 


- with commands that require drive information (backup, restore, 
label, join, subst, print) 


- during normal use of MS-DOS except as required by a program 


Two other commands, format and diskcopy, ignore drive reassignments. 
Examples: 


To reset all drives to their original assignments type the following command 
and press the RETURN key: 


assign 
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If you want to run an application on a hard disk drive, C, and this application 
requires you to put your program disk into drive A and your data disk into drive 
B, you would type this command: 

assign a=c b=c 

All references to drives A and B would then go to drive C. 
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Attrib [E] 


Purpose: 
Sets or displays file attributes. 


Syntax: 
attrib [+ r] [+a] [drive:]pathname [/s} 
where: 


+r sets the read-only attribute of a file. 
-r disables read-only mode. 

+a sets the archive attribute of a file. 
-a clears the archive attribute of a file. 


Comments: 


The attrib command sets read-only and/or archive attributes for files. You may 
use wildcards to specify a group of files. The attributes of those files matching 
filename are displayed or modified based on the switch selection. Attrib 
doesn’t accept a directory name as a valid filename. 


The drive and pathname specify the location of the file or files you want to 
reference. The /s switch processes all subdirectories as well as the path 
specified. 

The backup, restore, and xcopy commands use the archive attribute as a 
control mechanism. You can use the +a and -a options to select files that you 
want to back up with the backup /m command, or copy with the xcopy /m or 
xcopy /a commands. 

Notes: 

If an application creates a file that has read and write permission, attrib forces 
read-only mode to allow file sharing over a network. 

Examples: 


To display the attribute of a file called news86 on the default drive, you would 
type the following command: 


attrib news86 
The following command gives the file report.txt read-only permission: 
attrib +r report.txt 


Setting a file as read-only prevents you from accidentally deleting or modifying 
it. 
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To remove read-only permission from the files in the \ usr \ pete directory on 
drive B, and the files in any subdirectories, you would type the following 
command: 


attrib -r b:\user\pete /s 


As a final example, suppose you want to give a coworker a disk that contains 
all files in the default directory of the disk in drive A, except for files with the 
extension .bak that contain old copies of edited files. To copy these files to a 
disk in drive B, you would type the following: 


attrib ta a:*.* 

attrib -a a:*.bak 

and: 

xcopy a: b: /m 

or: 

copy a: b: /a 

If you use the xcopy /m switch, xcopy automatically turns off the archive bits 
of the files in drive A as it copies them. 
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Backup [E] 
Purpose: 


Backs up one or more files from one disk to another. 


Syntax: 


backup [drivel:][path] [filename] [drive2:} [/s][/m)][/a] [/f] [/d:date] [/t:time] 
[/L:[[drive:][path]filename]] 
where: 


drivel is the disk drive that you want to back up. 
drive2 is the target drive to which the files are backed up. 


Comments: 


The backup command can back up files on disks of different media (hard disks 
and floppy disks). Backup also backs up files from one floppy disk to another, 
even if the disks have a different number of sides or sectors. 


The backup command accepts the following switches: 


Switch Purpose 

/s Backs up subdirectories. 

/m Backs up only those files that have changed since the last 
backup. 

la Adds the files to be backed up to those already on the backup 


disk. It does not erase old files on the backup disk. This switch 
will not be accepted if files exist that were backed up using 
backup from MS-DOS version 3.2 or earlier. 


/f Causes the target disk to be formatted if it is not already. For this 
switch to function, the MS-DOS format command must be 
accessible by the current path. 


/d:date Backs up only those files that you last modified on or after date. 
/t:time Backs up only those files that you last modified at or after time. 
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/L:filename Makes a backup log entry in the specified file. If you do not 
specify filename, backup places a file called backup.log in the 
root directory of the disk that contains the files being backed up. 


A backup log file uses the following format: 
e The first line lists the date and time of the backup. 


e A line for each backed-up file lists the filename and number of the backup 
disk on which the file resides. 


If the backup log file already exists, backup appends the current entry to the 
file. 


You can also use the backup log file when you need to restore a particular file 
from a floppy disk, but you must specify which disk to restore so that the 
restore command does not have to search for files. The restore command 
always puts a file back in the same place from which it was backed up. Backup 
displays the name of each file as it is backed up. 


You should label and number each backup disk consecutively to help you 
restore the files properly with the restore command. If you are sharing files, 
MS-DOS lets you back up only those files to which you have access. 


Notes: 


e You cannot use an old version of the restore command (MS-DOS 3.2 or 
earlier) for files backed up with the MS-DOS 3.3 backup command. 


e Unless you use the /a switch, backup erases the old files on a backup disk 
before adding new files to it. 


e You should not use the backup command if the drive you are backing up 
has been assigned, joined, or substituted with the assign, join, or subst 
commands. If you do, you may not be able to restore the files with the 
restore command. 
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The backup program returns the following exit codes: 


Code Function 

Normal completion 

No files were found to back up 

Some files not backed up due to sharing conflicts 
Terminated by user 
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Terminated due to error 
You can use the batch processing if command for error processing that is based 


on the errorlevel returned by backup. 


Examples: 


Suppose Emily wants to back up all the files in the \user\emily directory on 
drive C to a blank, formatted disk in drive A. To do this, she would type 


backup c:\user\emily a: 
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Break [I] 
Purpose: 


Sets ConTROL-c check. 


Syntax: 


break [on] 
or 
break [off] 


Comments: 


Depending on the program you are running, you may use CONTROL-c to stop an 
activity (for example, to stop sorting a file). Normally, MS-DOS checks to see 
whether you press ConTROL-c while it is reading from the keyboard or writing to 
the screen or printer. If you set break to on, you extend controL-c checking to 
other functions, such as disk reads and writes. 


Notes: 


Some programs may set themselves to respond to ConTROL-C at any time. Setting 
break does not affect these programs. 


Examples: 


To check for controL-c only during screen, keyboard, and printer reads and 
writes, type the following: 

break off 

To find out how break is currently set, type the break command and press the 
RETURN key. 
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Chcp [I] 
Purpose: 


Displays or changes the current code page for the command processor 
command.com. 


Syntax: 


chep [nnn] 
where: 


nnn is the code page to start. 


Comments: 


The chcp command accepts one of the two prepared system code pages as a 
valid code page. An error message is displayed if a code page is selected that 
has not been prepared for the system. 

If you type the chcp command without a code page, chep displays the active 
code page and the prepared code pages for the system. 

You may select any one of the prepared system code pages defined by the 
country command in config.sys. 

The following are valid code pages: 


Value Code Page 

437 United States 
850 Multilingual 

860 Portuguese 

863 French-Canadian 
865 Nordic 


Any program that you run after starting a new code page will use the new code 
page. Programs that started before the new code page will still use the original 
code page. 

To see what the current code page setting is, you simply type 

chep 

MS-DOS will respond with a message similar to the following: 

Active code page: 850 

Prepared system code pages: 850 437 
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If you select a code page that is not prepared for the system, MS-DOS displays 
a message like the following: 


Code page 850 not prepared for system 
Active code page: 437 
Prepared system code pages: 437 865 


If a device (screen, keyboard, printer) is not prepared for a code page, MS-DOS 
displays the following error message: 


Code page 850 not prepared for device xxx 


Notes: 


e [n the preceding example, the chep command will still change the active 
code page even if the selected code page is not prepared for a device. If 
you want to change the active code page to the original code page, you 
must reissue the chep command with the original code page selected. 


Example: 


To set the code page for the current screen group to 863 (French-Canadian), 
you would type the following command: 


chep 863 
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Chdir i] 
Synonym: 

cd 

Purpose: 


Changes a directory to a different path; displays the working directory. 


Syntax: 


chdir [path] 


Comments: 


The chdir command changes your working directory to the directory you 
specify. A shorthand notation for the chdir command is cd. Thus, either of the 
following commands will change your current directory to the directory called 
primetim: 

chdir \primetim 

cd \primetim 

To display the name of your working directory, simply type: 

cd 

There are two shortcuts you can use when you want to change your directory to 
a parent directory or subdirectory of your working directory. To illustrate, 
suppose you have a directory called specials that has a subdirectory called 
sponsors. So to change your working directory to \specials\sponsors, you 
would type 

cd \specials\sponsors 

If your working directory is specials, you can type the following command to 
change to the \specials\sponsors directory: 

cd sponsors 

Then, if you wanted to change your working directory back to the parent 
directory, \specials, you could type this command: 

cd 
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Type cd \ to retum to the "root" directory. The root directory is the highest- 
level directory on your computer and is usually the directory that you see when 
you start MS-DOS. 


Examples: 


If you use chdir without a path, you can display the name of your working 
directory. For example, if your working directory is \user\pete on drive B, and 
you type the command, chdir b:, then press the rEruRN key, MS-DOS displays 
the following: 


b:\user\pete 
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Chkdsk [E] (sy) 


Purpose: 


Scans the disk in the specified drive and checks it for errors. 


Syntax: 


chkdsk [drive:][pathname] [/f] [/v] 


Comments: 


The chkdsk command shows the status of your disk. You should run chkdsk 
occasionally on each disk to check for errors. If you do run chkdsk on a disk 
and any errors are found, chkdsk displays the error messages, followed by a 

status report. 


A typical status report might look like this: 


160256 bytes total disk space 
8192 bytes in 2 hidden files 
512 bytes in 2 directories 
30720 bytes in 8 user files 

121344 bytes available on disk 


65536 bytes total memory 
53152 bytes free 


If you type a filename after chkdsk, MS-DOS displays a status report for the 
disk and for the individual file. 


The chkdsk command accepts the following switches: 


Switch Purpose 


/f Fixes errors on the disk. If you do not specify this switch, 
chkdsk does not correct errors that it finds in your directory. 
However, it does display messages about files that need to be 
fixed. 


lv Displays the name of each file in each directory as it checks the 
disk. 


If you specify the /f switch, chkdsk will show an error if it finds any open files 
on the disk. If you do not specify the /f switch and there are open files, chkdsk 
may give results that make it seem like there are lost clusters on the disk. This 
happens when the File Allocation Table has yet to be updated regarding open 
files. If chkdsk reports a large number of clusters as lost, you should consider 
repairing the disk. 
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Notes: 


e Chkdsk does not correct errors on a disk unless you specify the /f switch. 
For more information on chkdsk errors, refer to the specific error message 
in Appendix F, "MS-DOS Message Directory." 


e Chkdsk doesn’t work on drives used in the subst or join commands. 


Examples: 


If you want to save a chkdsk status report for future use, you can redirect the 
output from chkdsk to a file, status, by typing the following: 
chkdsk a:>status 


The errors are then sent to the specified file. Remember, though, not to use the 
/f switch when you redirect chkdsk output. 


If chkdsk finds errors on the disk in drive A and you want to try to correct 
them, type the following command: 


chkdsk a: /f 


Chkdsk now tries to correct any errors it finds on the disk in drive A, 
prompting you for further information when necessary. 
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Cls [I] 
Purpose: 


Clears the screen. 


Syntax: 


cls 


Comments: 


The cls command clears your screen, leaving only the MS-DOS prompt and a 
cursor. 


Examples: 


You may find it more comfortable to work with a "clean slate." If you want to 
start a new process with a clear screen, type 


cls 
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Command [E] 
Purpose: 


Starts the command processor. 


Syntax: 


command [drive:][path][ctty-dev] [/e:nnnnn][/p][/c string] 
where: 


ctty-dev allows you to specify a different device (such as AUX) for input and 
output. 


Comments: 


This command starts a new command processor (the MS-DOS program that 
contains all internal commands). 


When you start a new command processor, you also create a new command 
environment. This new environment is a copy of the old, parent environment. 
However, you can change the new environment without affecting the old one. 


The command processor is loaded into memory in two parts: transient and 
resident. Some applications write over the transient memory part of 
command.com when they run. When this happens, the resident part of the 
command processor looks for the command.com file on disk so that it can 
reload the transient part. 

The drive:path options tell the command processor where to look for the 
command.com file if it needs to reload the transient part into memory. 


The following switches are accepted by command: 


Switch Purpose 

/e:nnnnn Specifies the environment size, where nnnnn is the size in bytes, 
ranging from 160 to 32,768. MS-DOS rounds this number up to 
the next logical paragraph boundary. The default value is 160 
bytes. 

/p Keeps the secondary command processor in memory and does 
not automatically return to the primary command processor. 


[c string Tells the command processor to perform the command or 
commands specified by string and then to return automatically 
to the primary command processor. 
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If nnnnn is less than 160 bytes, MS-DOS defaults to 160 bytes and displays the 
following message: 


Invalid environment size specified 


If nnnnn is greater than 32,768 bytes, MS-DOS displays the same message, but 
defaults to 32,768 bytes. 


Notes: 


For more information about the ctty-dev option, see the ctty command in this 
chapter. 


Examples: 


The following command tells the MS-DOS command processor to do three 
things: 

e Start anew command processor under the current program 

e Run the command chkdsk b: 

e Retum to the first command processor 


command /c chkdsk b: 
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Comp [E] 
Purpose: 


Compares the contents of two sets of files. 


Syntax: 


comp [drive:][pathname]] [drive:][pathname2] 


Comments: 


The comp command compares one file or set of files (pathname!) with a 
second file or set of files (pathname2). These files can be on the same drive or 
on different drives. They can also be in the same directory or different 
directories. 


The two sets of files you want to compare can have the same path and 
filenames—provided they are on different drives. If you type only a drive for 
the second option, comp assumes that pathname2 is the same as pathname]. 
You can use wildcards (* and ?) to specify the pathnames. 


If you don’t type the pathname options or if you omit the pathname? option, 
comp prompts you for them. If either option contains only a drive or a path 
with no filename, comp assumes the filename is *.*. 


If the files you want to compare are on a different disk than comp, type the 
comp command with no options. When comp prompts you for the pathname 
options, you can insert the correct disk and type the filenames to be compared. 


As comp proceeds, it displays the paths and names of the compared files. A 
message appears if comp cannot find a file matching the pathname2 option, or 
if a directory path is invalid. If no file matches the pathname! option, comp 
prompts you for both the pathname options again. 


During the comparison, a message appears for any location in the two files that 
contains mismatching information. The message indicates the offset into the 
files of the mismatching bytes and the contents of the bytes themselves (all in 
hexadecimal] notation). The message has the following format: 


Compare error at OFFSET XXXXXXXX 
filel = XX 
file2 = XX 
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In this format, file/ is the first filename typed; file2 is the second filename 
typed. After ten unequal comparisons, comp stops comparing and displays the 
following message: 


10 Mismatches - ending compare 

If the file sizes are different, comp displays the following message: 

Files are different sizes, do you wish to continue 
(Y/N) ? 

You can either continue the comparison or end it. If you choose to continue, 
comp compares the files until it reaches the end of the shorter file. 

After a successful comparison, comp displays the following message: 

Files compare OK 

After the comparison of the two files ends, comp proceeds with the next pair of 
files that match the two pathname options, until no more files can be found that 
match the pathname! option. Then comp displays the following message: 
Compare more files (Y/N)? 

You now can compare two more files, or end the comparison. If you want to 
compare two more files, type Y (for Yes). Comp prompts you for two new path 
options. 

For all file comparisons, comp first ensures that both files include end-of-file 
(ConTROL-Z) marks. If they do not, comp displays this message and the files are 
not compared: 


EOF mark not found 


Examples: 


In the following example, comp compares each file with the extension .asm in 
the current directory on drive C with each file of the same name (but with an 
extension of .bak) in the current directory on drive B: 


comp c:*.asm b:*.bak 
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Copy [1] 
Purpose: 


Copies one or more files to another location. This command also appends files. 


Syntax: 


To copy files: 
copy [drive:]pathname] [drive:][pathname2] [/v]{/a][/b] 


or 
copy [drive:]pathname] [/v][/a][/b] [drive:][pathname2] 
To append files: 
copy pathname! + pathname? [...] pathnameN 


Comments: 


If you do not specify pathnamez2, the copy is created in the working directory 
on the disk in the default drive. This copy has the same name, creation date and 
creation time as the original file (pathname). If the original file is on the 
default drive and you do not specify pathname2, the copy command quits (you 
are not allowed to copy a file to itself), and MS-DOS displays the following 
error message: 

File cannot be copied onto itself 

O File(s) copied 


The copy command accepts the following switches: 


Switch Purpose 

lv Causes MS-DOS to verify that the sectors written on the target 
disk are recorded properly. 

/a Lets you copy ascu files. This switch applies to the filename 


preceding it, and to all remaining filenames in the command, 
until copy encounters another /a or /b switch. This switch tells 
the command processor to read until the end-of-file mark. 


/b Lets you copy binary files. This switch applies to the filename 
preceding it, and to all remaining filenames in the command, 
until copy encounters another /a or /b switch. This switch tells 
the command processor to read the number of bytes specified by 
the file size in the directory. 


If MS-DOS cannot verify a write, it displays an error message. 
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Although recording errors rarely occur with the copy command, the /v switch 
lets you verify that critical data has been correctly recorded; it also causes the 
copy command to run more slowly, because MS-DOS must check each entry 
recorded on the disk. 


Notes: 


e The copy command switches /a and /b perform differently depending on 
whether they are placed following the source filename or the target 
filename. 


When used with a source filename 
fa Causes the file to be treated as an ascu (text) file. Data in the file is 


copied up to but not including the first end-of-file mark (in Edlin, 
this is CONTROL-Z). The remainder of the file is not copied. 


/b Causes the entire file to be copied, including any end-of-file marks. 
When used with a target filename 
/a Causes an end-of-file character to be added as the last character of the 
file; for example: 
copy memo.doc /a letter.doc 
/b Does not add an end-of-file character; for example: 
copy billing.asm /b billing2.asm 


When you are combining files, the default switch is always /a. 


e Donot try to append files if one of the source filenames has the same 
name or extension as the target. 


e Ifyou want to copy all of a directory’s files and subdirectories, you should 
use the xcopy command. Refer to the xcopy command in this chapter for 
more information. 


Examples: 


To copy a file called animal.typ from your working drive and directory to a 
directory on drive C called bigcats, type 


copy animal.typ C:\bigcats 
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The copy command also lets you append files. To do this, simply list any 
number of files as options to copy, each separated by a plus sign (+), and then 
specify a target file to send the combined files to; for example: 


copy intro.rpt + body.rpt + b:sum.rpt report 


This command combines files named intro.rpt, body.rpt, and sum.rpt (from 
drive B), and places them in a file called report on the default drive. When you 
are appending files, the target file is created with the current date and time. If 
you omit the target file, MS-DOS combines the files, and stores them under the 
name of the first specified file. 


You can also combine several files into one by using wildcards; for example: 
copy *.txt combin.doc 


This command takes all files with an extension of .txt and combines them into 
one file named combin.doc. 

In the following example, each file that matches *.txt is combined with its 
corresponding .ref file. The result is a file with the same filename but with the 
extension .doc. Thus, file/ .txt is combined with filel.ref to form filel.doc, 
xyz.ba with xyz.ref to form xyz.doc, and so on: 


copy *.txt + *.ref *.doc 


The following copy command combines all files matching *.txt and all files 
matching *.ref, into one file named combin.doc: 

copy *.txt + *.ref combin.doc 

Copy compares the filename of the source file with the filename of the target. 
If they are the same, that one input file is skipped, and MS-DOS prints the error 
message, "Content of destination lost before copy." Further joining proceeds 
normally. For example, the following command appends all * txt files (except 
all.txt) to all. txt: 

copy all.txt + *.txt 


This command will not produce an error message. 
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Ctty [I] 
Purpose: 


Lets you change the device from which you issue commands. 


Syntax: 


ctty device 
where: 


device specifies the device from which you are giving commands to MS-DOS. 


Comments: 


Ctty is useful if you want to change the device on which you are working. In 
this command, the letters tty represent your terminal; that is your computer’s 
screen and keyboard. 


Notes: 


There are many programs that do not use MS-DOS for input, output, or either. 
These programs send input directly to the hardware on your computer. The ctty 
command has no effect on these programs; it affects only programs that use 
MS-DOS. 


Examples: 


The following command moves all command T/O (input/output) from the 
current device (the console) to an AUX port, such as another terminal: 


ctty aux 
The next command moves I/O back to the console screen and keyboard: 
ctty con 
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Date [I] 
Purpose: 


Displays or sets the date. 


Syntax: 


date [mm-dd-yy] 


Comments: 


You can change the date from your terminal or from a batch file. (MS-DOS 
does not automatically display a prompt for the date if you use an autoexec.bat 
file, so you may want to include a date command in that file.) MS-DOS records 
this date in the directory when you create or change a file. 


Remember to use only numbers when you type the date; allowed numbers are 
mm = 1-12 

dd = 1-31 

yy = 80-79 or 1980-2079 

The date, month, and year entries may be separated by hyphens (-) or slashes 
(/). MS-DOS is programmed to change months and years correctly, whether the 
month has 28, 29, 30 or 31 days. 


It is possible for you to change the mm-dd-yy format in which the date is 
displayed and entered. The country command in the config.sys file allows you 
to change the date format to the European standard dd-mm-yy. For more 
information on the config.sys file, see Appendix B, "How to Configure Your 
System.” 


Notes: 


e This command sets your computer’s internal clock in your computer, if 
one exists. 


e The format mm-dd-yy may vary if you are using a code page other than the 
one for the United States. For more information about international date 
formats, see Appendix E, "How to Use Code Pages.” 
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Examples: 


If you simply type the date command, MS-DOS displays the following 
message: 


Current date is weekday mm-dd-yy 
Enter new date (mm-dd-yy) :_ 


where weekday is the day of the week (for example, Tuesday). 

If you do not want to change the date shown, press the RETURN key. Or you can 
type a particular date after the date command, as in the following example: 
date 3-9-88 


In this case, the "Enter new date:" prompt does not appear after you have 
pressed the RETURN key. 
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Del (Erase) [I] 
Purpose: 


Deletes the specified files. 


Syntax: 


del [drive:]pathname 
or 
erase [drive: |pathname 


Comments: 


The del command lets you use the * and ? wildcards to delete more than one 
file at a time. While convenient, this method of deleting files can be dangerous, 
so use wildcards cautiously. 


If you type del *.*, this tells MS-DOS that you want to delete all the files in the 
working directory. MS-DOS displays the prompt "Are you sure?" If you type Y 
(for Yes) in response, MS-DOS deletes all files in the working directory. 

To delete all the files in another directory, type the del command followed by 
the directory name. 


Warning Once you have deleted a file from your disk, you cannot recover it. 


Examples: 


The following command deletes a file named vacation: 
del vacation 


If you have two files named vacation.feb and vacation.apr, you can delete them 
both with the following command: 


del vacation.* 
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Dir [I] 
Purpose: 


Lists the files in a directory. 
Syntax: 


dir [drive:] [pathname] [/p][/w] 
Comments: 


The dir command, typed by itself, lists all directory entries in the working 
directory on the default drive. If you include a drive name, such as b:, with the 
dir command, all entries in the default directory of the disk in the specified 
drive are listed. 


The dir command accepts the following switches: 


Switch Purpose 


/p Selects page mode, causing the directory display to pause once the 
screen is filled. To resume scrolling the display, press any key. 

lw Selects wide display and causes MS-DOS to display only filenames 
and not other file information. The wide display lists up to five files 
per line. 


Dir lists all files with their size in bytes and the time and date of last 
modification. 


Note that the following dir commands are equivalent, since you can use the 
wildcards ? and * in the pathname option: 


This command Is equivalent to 


dir dir *.* 

dir filename dir filename.* 
dir .ext dir * ext 
Notes: 


If the country command in the config.sys file is set to a country other than the 
United States, the directory date and time formats may differ. For more 
information on the config.sys file, see Appendix B, "How to Configure Your 
System.” 
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Examples: 


If your directory contains more files than you can see on the screen at one time, 
type the following: 

dir /p 

This command displays the directory one screen at a time. As one screen fills 
up, you can press any key to see the next screen of the directory listing. 
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Diskcomp [E] (ty) 
Purpose: 


Compares the contents of the disk in the source drive to the disk in the target 
drive. 


Syntax: 


diskcomp [drivel :] (drive2:] [/l] [/8] 
where: 


drivel is the source drive. 
drive2 is the target drive. 


Comments: 


Diskcomp performs a track-by-track comparison of the disks. It automatically 
determines the number of sides and sectors per track based on the format of the 
source disk. 


The diskcomp command accepts the following switches: 


Switch Purpose 


A Causes diskcomp to compare just the first side of the disk, even if the 
disks and drives that you are using are double-sided. 


/8 Causes diskcomp to compare just the first 8 sectors per track, even if 
the disks contain 9 or 15 sectors per track. 


If you specify only one drive, diskcomp uses the default drive as the target 
drive. If you specify the same drive as the source and target, diskcomp does a 
comparison using one drive, and prompts you to insert the disks as appropriate. 


If all the tracks are the same, diskcomp displays the message: 
Compare OK 


If the tracks are not the same, diskcomp displays a "Compare error" message 
that includes the track number and side number (0 or 1) where it found the 
mismatch. 

If the target disk is not the same type as the disk in the source drive, diskcomp 
displays the following message: 


Drive types or diskette types not compatible 
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When diskcomp completes the comparison, it prompts you with the following 
message: 


Compare another diskette (Y/N)?_ 


If you type Y (for Yes), diskcomp prompts you to insert the proper disks and 
does the next comparison. If you type N (for No), diskcomp ends. If the disk in 
the default drive does not contain MS-DOS and you end diskcomp, you’ll 
receive the following message: 


Insert disk with COMMAND.COM in drive A 
and strike any key when ready 


Diskcomp does not work on network drives, and you cannot use it with 
assigned, joined, or substituted drives. If you attempt to use the diskcomp 
command with these types of drives, it displays an error message. 


Notes: 


e When comparing a disk with a backup disk that you made with the copy 
command, you may receive the "Compare error" message, even if the files 
on the disks are identical. This is because the copy command duplicates 
the information, but doesn’t necessarily place it in the same location on 
the target disk. In this case, you should use the fe command to compare 
individual files on the disk. For more information, see the fe command 
later in this chapter. 


e Diskcomp does not work on network drives, and you cannot use it with 
assigned, joined, or substituted drives. If you try to use the diskcomp 
command with these types of drives, an error message will appear. 


e The diskcomp command returns the following exit codes: 


Code Function 
0 Compared OK 

The disks compared exactly. 
1 Did not compare 


The disks were not the same. 
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2 CONTROL-C error 
The user terminated with CONTROL-c. 


3 Hard error 
An unrecoverable read or write error occurred — did not 
compare. 


4 Initialization error 
There is not enough memory — invalid drives or command 
line syntax. 


You can use the batch processing if command to perform error processing 
based on the errorlevel returned by diskcomp. 


Examples: 


If your computer has only one floppy disk drive, drive A, and you want to 
compare two disks, you can simply type the following command: 


diskcomp a: 
MS-DOS prompts you to insert each disk, as required. 
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Diskcopy [E] A) 


Purpose: 


Copies the contents of the floppy disk in the source drive to a formatted or 
unformatted floppy disk in the target drive. 


Syntax: 


diskcopy [drivel:] [drive2:] [/1] 
where: 


drivei is the source drive. 
drive2 is the target drive. 


Comments: 


Drivel and drive2 may be the same. If you omit the drive options, MS-DOS 
prompts you for the drives. If the target disk is not formatted, diskcopy formats 
it with the same number of sides and sectors per track as the source disk. 


The /1 switch allows you to copy only one side of a disk. 


Warning The diskcopy command works only with floppy disks. You cannot 
use diskcopy with a hard disk. 


If you omit both options, MS-DOS performs a single-drive copy operation on 

the default drive. If you omit just the second option, MS-DOS uses the default 
drive as the target drive. In either case, though, diskcopy destroys the contents 
of the target disk. 


Diskcopy prompts you to insert the source and target disks at appropriate times 
and waits for you to press any key before continuing. 


After copying, diskcopy then prompts you with the following message: 
Copy another diskette (Y/N) ?_ 


If you type Y (for Yes), MS-DOS prompts you to insert source and target disks, 
and performs the next copy on the drives that you originally specified. 


To end the diskcopy process, type N (for No). 


Because disk space is not allocated sequentially, disks that have had a lot of 
files created and deleted on them become fragmented. As a result, the first free 
sector found by diskcopy becomes the next sector allocated, regardless of its 
location on the disk. 
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A fragmented disk can delay finding, reading, or writing a file. To prevent 
further fragmentation, you should use either the copy command or the xcopy 
command to copy your disk, instead of using the diskcopy command. Because 
the copy and xcopy commands copy files sequentially to a disk, the new disk 
will not be fragmented. 


The following command, for example, copies all files from the disk in drive A 
to the disk in drive B: 


xcopy a:*.* b: 


Diskcopy figures out the number of sides to copy, based on the source drive 
and disk. 


Notes: 


The diskcopy command returns the following exit codes: 


Code Function 


0 Copied successfully 

1 Non-fatal read/write error 
An unrecoverable but non-fatal read or write error occurred. 

2 CONTROL-C error 
The user entered ConTROL-c to terminate diskcopy. 

3 Fatal hard error 
Diskcopy was unable to read the source disk or format the target 
disk. 

4 Initialization error 
There is not enough memory—invalid drives or command line 
syntax. 


You can use the batch processing if command to perform error processing 
based on the errorlevel returned by diskcopy. 


Examples: 


To copy the disk in drive A to the disk in drive B, use the following command: 
diskcopy a: b: 
Diskcopy prompts you to insert both disks and press any key to begin copying. 
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Exe2bin [E] 
Purpose: 


Converts .exe (executable) files to binary format. 


Syntax: 


exe2bin [drive:]pathnamel [drive:]pathname2 
where: 


pathname! is the input file. 
pathname? is the output file. 


Comments: 


This command converts .exe (executable) files to binary format. If you do not 
specify an extension for pathname], it defaults to .exe. The input file is 
converted to a .bin file format (a memory image of the program) and placed in 
the output file (pathname?2). 


If you do not specify a drive name, exe2bin uses the drive of the input file. 
Similarly, if you do not specify an output filename, exe2bin uses the input 
filename. And finally, if you do not specify a filename extension in the output 
filename, exe2bin gives the new file the extension .bin. 


Some restrictions do apply when you use the exe2bin command: the input file 
must be in valid .exe format produced by the linker; the resident, or actual code 
and data part of the file must be less than 64K bytes; and there must be no 
STACK segment. 


With exe2bin, two kinds of conversions are possible, depending on whether the 
initial CS:IP (Code Segment: Instruction Pointer) is specified in the .exe file: 


e If the CS:IP is not specified in the .exe file, exe2bin assumes you want a 
pure binary conversion. If segment fixups are necessary (that is, if the 
program contains instructions requiring segment relocation), the exe2bin 
command prompts you for the fixup value. This value is the absolute 
segment at which the program is to be loaded. The resulting program will 
be usable only when loaded at the absolute memory address specified by 
your application. The command processor will not be able to load the 
program. 


MS-DOS Commands 3.45 


If the CS:IP is 0000:100H, exe2bin assumes that the file will run as a 
.com file with the location pointer set at 100H by the assembler statement 
ORG (the first 100H bytes of the file are deleted). No segment fixups are 
allowed, since .com files must be segment relocatable; that is, they must 
assume the entry conditions explained in the Microsoft Macro Assembler 
manuals (User's Guide and Reference Manual). Once the conversion is 
complete, you may rename the output file with a .com extension. The 
command processor will then be able to load and execute the program in 
the same way as the .com programs supplied on your MS-DOS disk. 


3.46 MS-DOS User's Reference 


Exit [E] 
Purpose: 


Exits the command.com program (the command processor) and returns to a 
previous level, if one exists. 


Syntax: 


exit 


Comments: 


If you use the MS-DOS command program to start a new command processor, 
you can use the exit command to return to the old command processor. Also, 
while running an application program, you can exit to the MS-DOS command 
processor, and then return to your program. 


For more information about command processors, see the command command 
earlier in this chapter. 


Examples: 


If you start a new command processor by typing the following command: 
command c:\ 


you can then return to the previous command processor by typing the exit 
command: 


exit 
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Fastopen [E] (3) 
Purpose: 


Decreases the amount of time needed to open frequently-used files and 
directories. 


Syntax: 


fastopen [drive:[=nnn][...]] 
where: 
nnn is the number of files per disk. 


Comments: 


Fastopen tracks the location of files and directories on a disk for fast access. 
Access to files in a complex directory structure can be time consuming. If you 
run applications that use several files (such as a data base application), the time 
to open and close files noticeably degrades your computer’s performance. 


Every time a file or directory is opened, fastopen records its name and 
location. Then, if a file or directory recorded by fastopen is reopened, the 
access time is greatly reduced. 

Fastopen works only on hard disks, and will not work over a network. You can 
use fastopen with up to four hard disks at one time. For each hard disk, 
fastopen will track nnn files or directories, where nnn ranges from 10 to 999. 
The default is 10. 


Notes: 


e You can invoke the fastopen command only once. If you want to change 
the fastopen settings, restart MS-DOS. 


e Fastopen needs approximately 40 bytes of memory for each file or 
directory location it tracks. 


Examples: 


If you want MS-DOS to track the location of up to 100 files on drive C, you 
could type the following: 


fastopen c:=100 
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Fc [E] 
Purpose: 


Compares two files or two sets of files and displays the differences between 
them. 


Syntax: 


For ascu comparisons: 

fe [/a] (/c] [/L] [/Lb n] [/n] [/t] /w] [/nnnn][drive:]pathname! 
[drive:]pathname2 

For binary comparisons: 

fe [/b] [/nnnn][drive:]pathnamel1 [drive:]pathname2 

where: 


pathnamel is the first file that you want to compare. 
pathnamez is the second file that you want to compare. 


Comments: 


Fc matches the first file against the second and reports any differences between 
them. 


The nine switches that you can use with the fe command are described as 
follows: 


Switch Purpose 


/a Abbreviates the output of an ascu comparison. Instead of displaying 
all the lines that are different, fe displays only the lines that begin and 
end each set of differences. 


[b Forces a binary comparison of both files. Fe compares the two files 
byte-by-byte, with no attempt to resynchronize after a mismatch. The 
mismatches are printed as follows: 


XIAN: YY ZZ 
(where x220000cx is the relative address from the beginning of the file 
of the pair of bytes). Addresses start at 00000000; yy and zz are the 
mismatched bytes from pathname! and pathname2, respectively. The 
/b switch is the default when you compare.exe, .com, .sys, .obj, lib, 
or .bin files. 
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Ic Causes the matching process to ignore the case of letters. Fe then 
considers all letters in the files as uppercase letters. 

/L Compares the files in ascu mode.This switch is the default when you 
compare files that do not have extensions of .exe, .com, .sys, .obj, .lib, 
or .bin. 


/Lb Sets the internal line buffer to n lines. The default length of the 
internal buffer is 100 lines. Files that have more than this number of 
consecutive, differing lines will abort the comparison. 


/n Displays the line numbers on an asc comparison. 


it Does not expand tabs to spaces. The default is to treat tabs as spaces 
to 8-column positions. 

[w Causes fe to compress white space (tabs and spaces) during the 
comparison. If a line contains many spaces or tabs in a row, these 
characters are considered a single white space. 


Note that although fe compresses white space, it does not ignore it. 
The two exceptions are beginning and ending white spaces in a line, 
which are ignored. 


/nnnn Specifies the number of lines that must match after fe finds a 
difference between files. If the number of matching lines in the files 
is less than this number, fe displays the matching lines as differences. 


Fc reports differences between two files by displaying the first filename, 
followed by the lines that differ between the files, followed by the first line to 
match in both files. Fe then displays the name of the second file, followed by 
the lines that are different, followed by the first line that matches. 


The default value for the number of lines to match between the files is 2. If you 
want to change this default, specify the number of lines with the /nnnn switch. 


Fc uses a large amount of memory (enough to hold 100 lines) as buffer storage 
space to hold the text files. If these files are larger than available memory, fc 
compares what it can load into the buffer space. If it doesn’t find a match in 
those portions of the files in the buffer space, fc stops and displays the 
following message: 


resynch failed. Files are too different. 
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For binary files larger than available memory, fe compares both files 
completely, overlaying the portion in memory with the next portion from disk. 
All differences are output in the same manner as for those files that fit 
completely in memory. 


Examples: 


Suppose you want to compare two text files called monthly.rpt and sales.rpt. 
To make this comparison, you would simply type the following command line: 


fc /a monthly.rpt sales.rpt 


If you want to check for differences in files that are not ascu text files, you can 
use the /b switch to force a binary comparison of the files. For example, if you 
have two executable program files called profits.exe and earnings.exe, and you 
want to find out whether they are the same, you could type the following: 


fc /b profits.exe earnings.exe 
The output from this command line might be similar to the following: 


00000002: fc b6 
00000004: 12 14 
0000000e: 56 92 
00000012: e8 5c 
00000013: bb 7c 
00000014: 14 Oe 
00000015: Oa Od 
o00000le: 43 7a 
o000001f: 09 Oa 
00000022: be e6 


000005e0: 00 61 
000005e1: 00 73 
000005e2: 00 73 
000005e3: 00 69 
000005e4: 00 67 
000005e5: 00 6e 
000005e6: 00 6d 
000005e7: 00 65 
000005e8: 00 6e 
fc: earnings.exe longer than profits.exe 


If the profits.exe and earnings.exe files were identical, fe would display the 
following message: 


fc: no differences encountered 
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Fdisk E] @) 


Purpose: 


Configures a hard disk for use with MS-DOS. 


Syntax: 


fdisk 


Comments: 


The fdisk command displays a series of menus to help you partition your hard 
disk for MS-DOS. With the fdisk command, you can 


e Create a primary MS-DOS partition 

e Create an extended MS-DOS partition 
e Change the active partition 

e Delete a MS-DOS partition 

e Display partition data 


e Select the next fixed disk drive for partitioning on a system with multiple 
fixed disks 


Notes: 


e Fdisk doesn’t work on drives used in the subst or join commands. 


e For more information on how to use fdisk, see Appendix D, "Configuring 
Your Hard Disk (Fdisk)." 
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Find [E] 
Purpose: 


Searches for a specific string of text in a file or files. 


Syntax: 


find [/v] [/c] [/n] "string" [[drive:][pathname] ...] 
where: 
"string" is a group of characters you want to search for. 


Comments: 


The find command looks for string in one or more files. After searching the 
specified files, find displays any lines it has found that contain the specified 
string. 

String must be enclosed in quotation marks. Uppercase characters in string will 
not match lowercase characters. 


If string contains quotation marks, you must enclose it in an additional pair 
(" "string" ") 


If you omit pathname, find acts as a filter. It takes input from the MS-DOS 
standard input (usually from the keyboard, a pipe, or redirected file) and 
displays any lines that contain string. 


Wildcards (* and ?) are not allowed in filenames or extensions. 


The find command accepts the following switches: 


Switch Purpose 


lv Displays all lines not containing the specified string. 

le Displays only the number of lines that contain a match in each of the 
files. 

/n Precedes each line with its relative line number in the file. 


If you specify the /e switch with the /v switch, find displays the number of lines 
that do not contain the string you typed. If you specify the /c switch with the /n 
switch, find ignores the /n switch. 
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Examples: 


The following command displays all lines from the file pencil.ad that contain 
the string "Pencil Sharpener": 

find "Pencil Sharpener" pencil.ad 

The next command causes MS-DOS to display the names of all files on the disk 
in drive B that do not contain the string "date": 

dir b: ! find /v "date" 

If you want to find the string, "The dentist said, "Open wide!"”, in the file 
story.doc, type the following command: 

find ‘The dentist said, ""Open wide!""" story.doc 


Note that in this last example, the entire phrase you were searching for was set 
off by single quotation marks rather than double quotation marks. When you 
use unique marks to set off the phrase, find will not mistake the quotation 
marks for part of the phrase itself. 
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Format [E] (fey) 
Purpose: 


Formats the disk in the specified drive to accept MS-DOS files. 


Syntax: 
format drive:[/1}[/4][/8] [/t:tracks}[/n:sectors][/v][/s} 


or 
format drive:[/1][/b][/t:tracks][/n:sectors] 


Comments: 


The format command creates the directory and the file allocation tables on a 
disk. You must use this command to format all new disks before MS-DOS can 
use them. 


Warning Formatting destroys any previously existing data on a disk and it 
ignores drive assignments created with the assign command. 


You must specify the drive that you want to use to format a disk. Format then 
uses the drive type to determine the default format for a disk. 


The format command accepts the following switches: 


Switch Purpose 
Al Formats a single-side of the floppy disk. 
14 Formats a 5.25-inch, double-sided disk in a high-capacity disk 


drive. If you are using a single- or double-sided drive, you may 
not be able to reliably read disks formatted with this switch. 


/8 Formats eight sectors per track. 

[b Formats the disk, leaving ample space to copy an operating 
system, such as MS-DOS 3.3. 

Is Copies the operating system files listed in the file formats.tbl 


from the disk in the default drive to the newly formatted disk. 
The newly formatted disk must be 1.2 megabytes or greater in 
size; otherwise, format rejects the command. If the operating 
system is not on the default drive, format prompts you to insert 
a system disk in the default drive (or in drive A if the default 
drive is nonremovable). 
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[t:tracks Specifies the number of tracks on the disk. This switch formats 
3.5-inch floppy disk to the number of tracks specified. For 
720K-byte disks and 1.44-megabyte disks, this value is 80 
(/t:80). 

/n:sectors Specifies the number of sectors per track. This switch formats a 
3.5-inch disk to the number of sectors specified. For 720K-byte 
disks, this value is 9 (/n:9). 

lv Causes format to prompt you for a volume label for the disk 
you are formatting. A volume label identifies the disk and can be 
up to 11 characters in length (no tabs allowed). An example of a 
volume label is programs. 


When you format a hard disk, format prompts you to verify the volume label: 
Enter current Volume Label for drive x: 

If your hard disk does not have a volume label, press the RETURN key. But note 
that if your hard disk has never been formatted before, or if it has a bad boot 
sector, format will not prompt you for a volume label. 


If the volume label that you enter does not match the label on the hard disk, 
format displays the following message: 

Invalid Volume ID Format failure 

Otherwise it continues: 

WARNING, ALL DATA ON NON-REMOVABLE DISK 

DRIVE X: WILL BE LOST! 

Proceed with Format (Y/N) ?_ 

If you want to format your hard disk, type Y (for Yes) and press the RETURN key. 
If you don’t want to format your hard disk, type N (for No) and press the 
RETURN key. 

When formatting is complete, format displays a message showing the total 


disk space, any space marked as defective, the total space used by the operating 
system (when you use the /s switch), and the space available for your files. 
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Notes: 


You should not use the format command with drives used in the assign, 
join, or subst commands, and you cannot format drives over a network. 
For more information about formatting your hard disk, see Appendix D, 
"Configuring Your Hard Disk (Fdisk)." 

For more information about disk volume labels, see the dir, label, and 
volume commands in this chapter. 

The following table shows which switches you can use for certain types of 
disks: 


Disk type Valid switches 

160/180K bytes /1 /4 /8 /b /n /t /v /s 
320/360K bytes /1 /4 /8 /b /n /t /v /s 
720K bytes /n /t /v /s 
1.2 megabytes /n /t /v /s 
1.44 megabytes /n /t /v /s 
hard disk /v /s 


The format command returns the following exit codes: 


Code Function 


0 Successful completion 

3 Terminated by user (CONTROL-c) 

4 Fatal error (any error other than 0, 3, or 5) 

5 N response to hard disk prompt, "Proceed with format (Y/N)?" 


You can check these exit codes by using the errorlevel condition with the 
if batch processing command. 
You can use the select command instead of format if you want to format a 


disk with country-specific information. For more information, see the 
select command later in this chapter. 
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Examples: 


To format a floppy disk in drive A and copy the operating system to it, type the 
following command: 

format a: /s 

To format a floppy disk in drive A for use with data, type 


format a: /v 
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Graftabl [E] 
Purpose: 


Enables an extended character set to be displayed when using display adapters 
in graphics mode. 
Syntax: 


graftabl [xc] 
or 

graftabl /status 
where: 


xx is a code page identification number. 


Comments: 


Valid code pages (xxx) include the following: 


Value Code Page 

437 United States (default) 
850 Multilingual 

860 Portuguese 

863 French-Canadian 

865 Nordic 


If you type the graftabl command followed by the /status switch, MS-DOS 
displays the active character set. 


After graftabl loads the character table, it displays the following message: 
Graphics characters loaded 


Since you can load the graphics table only once each time you start MS-DOS, 
you might want to put the graftabl command in your autoexec.bat file to save 
time. If you try to load the same table a second time, graftabl displays the 
following message: 


Graphics characters already loaded 
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Notes: 


e The graftabl command increases the size of MS-DOS resident in 
memory. 


e For more information about using code pages, see the chcp command in 
this chapter. 


e The graftabl command returns the following exit codes: 


Code Function 

0 Command successful 

1 Table already loaded 

2 File error occurred 

3 Incorrect parameter, no action taken 


4 Incorrect version of MS-DOS; version 3.3 required 


You can check these exit codes using the errorlevel condition with the if batch 
processing command. 


Examples: 


To load a table of graphics characters into memory, type 
graftabl 
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Graphics [E] 
Purpose: 


Lets you print a graphics display screen on a printer when you are using a color 
or graphics monitor adapter. 


Syntax: 


graphics [printer] [/b][/p=port][/r][/lcd] 
where: 
printer is one of the following: 


Value Function 
COLOR1 Prints on an IBM Personal Computer Color Printer with black 
ribbon. 


COLOR4 Prints on an IBM Personal Computer Color Printer with RGB 
(red, green,blue, and black) ribbon. 


COLOR8 Prints on an IBM Personal Computer Color Printer with CMY 
(cyan, magenta, yellow, and black) ribbon. 


COMPACT Prints on an IBM Personal Computer Compact Printer. 
GRAPHICS Prints on an IBM Personal Graphics Printer, or IBM Proprinter. 
THERMAL Prints on an IBM PC-convertible. 


Comments: 


If you do not specify the printer option, graphics defaults to the GRAPHICS 
printer type. 
The graphics command accepts the following switches: 
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Switch Purpose 

lb Prints the background in color. This option is valid for COLOR4 
and COLORS printers. 

/p=port Sets the parallel printer port that graphics sends its output to 


when you press the SHIFT-PRINT-SCREEN key combination. The port 
may be set to 1, 2, or 3; the default setting is 1. 


ir Prints black and white (as seen on the screen) on the printer. The 
default is to print black as white and white as black. 
[cd Prints from the LCD (liquid crystal display) on the IBM PC- 


Portable computer. 


To print the screen, press the sHIFT and PRINTSCREEN keys at the same time. If the 
computer is in 320 X 200 color graphics mode, and if the printer type is 
COLOR1 or GRAPHICS, graphics prints the screen contents with up to four 
shades of gray. If the computer is in 640 X 200 color graphics mode, graphics 
prints the screen contents sideways on the paper. 


Notes: 


The graphics command increases the size of MS-DOS resident in memory. 


Examples: 


To print a graphics screen on your printer, type the following command: 
graphics 


Then, when the screen displays the information you want to print, press the 
SHIFT and PRINTSCREEN keys at the same time. 
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Join [E] (e) 
Purpose: 


Joins a disk drive to a specific path. 


Syntax: 

join [drive: drive:path] 
or 

join drive: /d 


Comments: 


With the join command, you don’t need to name physical drives with separate 
drive letters. Instead, you can refer to all the directories on a specific drive with 
one path. If the path already existed before you gave the join command, you 
cannot use it while the "join" is in effect. Also, you cannot join a drive if it is 
being used by another process. 


If the path does not exist, MS-DOS tries to make a directory with that path. 
After you give the join command, the first drive name becomes invalid, and if 
you try to use it MS-DOS displays the "Invalid drive" error message. 


Notes: 


The following commands do not work on drives used in the join command (or 
the subst command): 


chkdsk label 
diskcopy recover 
fdisk sys 
format 

Examples: 


You can join a drive only with a root-level directory. For example, this 
command will work: 


join d: c:\sales 

But the following one will not: 

join d: c:\sales\regional 

To reverse join, use the following format: 
join drive: /d 
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Here, drive: represents the source drive, and the /d switch turns off the join 
command. 

If you type just the join command by itself, MS-DOS displays the current 
drives that are joined. 
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Keyb [E] 


Purpose: 


Loads a keyboard program. 


Syntax: 


keyb [xx[,[yyy),[[drive:][path]filename]]] 
where: 

xx is a two-letter country code. 

yyy is the code page which defines the character set. 
filename is the name of the keyboard definition file. 


Comments: 


xx is one of the following two-letter codes: 


Code Keyboard type Command 
us United States keyb us (default) 
fr France keyb fr 

gr Germany keyb gr 

it Italy keyb it 

sp Spain keyb sp 

uk United Kingdom keyb uk 

po Portugal keyb po 

sg SwissGerman keyb sg 

sf Swiss-French keyb sf 

df Denmark keyb dk 

be Belgium keyb be 

nl Netherlands keyb nl 

no Norway keyb no 

la Latin America keyb la 

sv Sweden keyb sv 

su Finland keyb su 


If you type keyb without options, MS-DOS displays a message like the 
following to show the current keyboard code and its related code page, and the 
current code page used by your console screen device (CON): 


Current keyboard code: FR Code page: 437 
Current CON code page: 437 
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You can switch from the keyb program to the default (United States) keyboard 
format at any time by pressing CONTROL-ALT-F1. You can then return to the 
memory-resident keyboard program by pressing CONTROL-ALT-F2. 


The keyb command lets you use characters that are not part of the normal 
(QWERTY) keyboard format. Using the keyb command with one of the two- 
letter codes above, you can type commands or text to MS-DOS using either the 
standard keyboard or a special keyboard. 


Note that the characters that appear on your screen when you type on a standard 
keyboard do not necessarily match the label on the key. You can produce some 
characters in the non-United States keyboard sets by pressing CONTROL-ALT along 
with an appropriate character key. To produce accented (and umlauted) 
characters, you press dead keys. Dead keys are keys that do not display a 
character when used alone, but when followed by a letter, display that letter 
with an accent. 


Notes: 


You can also include the appropriate keyb command in your autoexec.bat file 
so that you won’t have to type it each time you start MS-DOS. 


Examples: 


To use a German keyboard, type the following command: 
keyb gr 
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Label [E] (fey) 


Purpose: 





Creates, changes, or deletes the volume label on a disk. 


Syntax: 


label [drive:] [label] 
where: 


label is the new volume label, up to 11 characters. 


Comments: 


A volume label is a name you can specify for a disk. MS-DOS displays the 
volume label of a disk as a part of its directory listing to show you which disk 
you are using. 


If a volume serial number exists, label will also display this eight-character 
number: 


Volume Serial Number in drive x is nnnn-nnnn 
If you do not specify a label, label prompts you with the following message: 


Volume in drive x is OO 
Type a volume label of up to 11 characters or 
press Enter for no volume label update: _ 


A volume label may be up to 11 characters in length and may include spaces, 
but not tabs. Type the volume label that you want and press the reTurN key. Or, 
you can press the RETURN key immediately if you want to delete the volume 
label. Label will prompt you with the message: 


Delete current volume label (Y/N) ?_ 


If you type Y (for Yes), label deletes the volume label on the disk. Otherwise, 
the volume label stays the same. 


Notes: 


° You can use the MS-DOS dir or vol command to determine if the disk 
already has a volume label. 


e Label doesn’t work on drives involved with subst or join commands. 
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e Do not use any of the following characters in a volume label: 
*?/\i. i t=<>[]()&A 


Examples: 


To label a disk in drive A that contains sales information for 1987, you might 
type 
label a:sales1987 
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Mkdir E 
Synonym: 


md 


Purpose: 


Makes a directory. 


Syntax: 
mkdir [drive:]path 


Comments: 


The mkdir command lets you create a multilevel directory structure. 
Remember, however, that directories created with mkdir are always 
subdirectories of your working directory unless you explicitly specify a 
different path with the mkdir command. 


Notes: 


You cannot specify a drive before this command. For example, you could not 
type a:mkdir newdir because MS-DOS always assumes that the mkdir 
command is on the current drive. 


Examples: 


If you want to create a directory to keep all your tax information, you could 
type the following command from your root directory: 


mkdir \taxes 


Now, suppose you want to create a directory named rental under the Vaxes 
directory to keep track of information about a duplex that you rent out. To do 
this from the root directory, you simply type the following command: 


mkdir \taxes\rental 


To create the same subdirectory from the Naxes directory, you could type either 
the previous command, or 


mkdir rental 
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Mode [E] 
Purpose: 


Sets operation modes for devices. 


Syntax: 


Parallel printer mode: 
mode LPTn[:][chars][,[lines][,p]] 


Asynchronous communications mode: 
mode COMn[:)baud[,parity[,databits [,stopbits[,p]]]] 


Redirecting parallel printer output: 
mode LPTn[:]=COMm[:] 


Display modes: 
mode display 


or 
mode [display],shift[,t] 


Device code page modes: 
mode device codepage prepare=([[yyy][drive: ][path]filename] 


and 

mode device codepage select=yyy 
mode device codepage refresh 
mode device codepage [/status] 


Comments: 


The mode command prepares MS-DOS for communication with devices such 
as parallel and serial printers, modems, and console screens. It also prepares 
parallel printers and console screen devices for code page switching. And, you 
can use the mode command to redirect output. 


Parallel printer modes 


For parallel printer modes, you can use PRN and LPT1 interchangeably. You 
can use the following options with the mode command to set parameters for a 
parallel printer: 
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Option 
n 
chars 
lines 

p 


Purpose 

Specifies the printer number: 1, 2, or 3. 

Specifies characters per line: 80 or 132. 

Specifies vertical spacing, lines per inch: 6 or 8. 

Specifies that mode tries continuously to send output to the 


printer if a time-out error occurs. This option causes part of the 
mode program to remain resident in memory. 


The default settings are LPT1, 80 characters per line, and 6 lines per inch. You 
can break out of a time-out loop by pressing CONTROL-BREAK. 


Asynchronous communication modes 


You can use the following options with the mode command to set parameters 
for serial ports: 


Option 
m 


baud 


parity 


databits 
stopbits 


P 


Purpose 

Specifies the asynchronous communications (COM) port 
number: 1, 2, 3, or 4. 

Specifies the first two digits of the transmission rate: 110, 150, 
300, 600, 1200, 2400, 4800, 9600 or 19,200. 

Specifies the parity: N (none), O (odd), or E (even). The default 
value is E. 

Specifies the number of data bits: 7 or 8. The default value is 7. 


Specifies the number of stop bits: 1 or 2. If baud is 110, the 
default value is 2; otherwise, the default value is 1. 

Specifies that mode is using the COM port for a serial printer 
and continuously retrying if time-out errors occur. This option 
causes part of the mode program to remain resident in memory. 


The default settings are COM1, even parity, and 7 databits. 
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Display modes 


You can use the following options with the mode command to set parameters 


for a display: 
Option 
display 


shift 


Purpose 


Specifies one of the following values: 40, 80, BW40, BW80, 
CO40, CO80, or MONO. 


40 and 80 indicate the number of characters per line. 


BW and CO refer to a color graphics monitor adapter with color 
disabled (BW) or enabled (CO). 

MONO specifies a monochrome display adapter with a constant 
display width of 80 characters per line. 

Specifies whether to shift the display to the left or to the right. 
Valid values are L (for left) or r (for right). 


Tells MS-DOS to display a test pattern in order to align the 
display on the screen. 


Device code page modes 


You can use the mode command to set or display code pages for parallel 
printers or your console screen device. You can use the following options with 
mode to set or display code pages: 


Option 
device 


XYY 


filename 


Purpose 


Specifies the device to support code page switching. Valid 
device names are con, LPT1, LPT2, and LPT3. 


Specifies a code page. Valid code pages are 437, 850, 860, 863, 
and 865. 


Identifies the name of the Code Page Information (.cpi) file MS- 
DOS should use to prepare a code page for the device specified. 
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There are four keywords that you can use with the mode device codepage 
command. Each causes the mode command to perform a different function. 
The following table explains each keyword: 


Keyword 
prepare 
select 
refresh 


/status 


Function 


Tells MS-DOS to prepare code pages for a given device. You 
must prepare a code page for a device before you can use it with 
that device. 


Specifies which code page you want to use with a device. You 
must prepare a code page before you can select it. 


If the prepared code pages for a device are lost due to hardware 
or other error, this keyword reinstates the prepared codepages. 


Display the current code pages prepared and/or selected for a 
device. Note that the following commands both produce the 
same results: 


mode con codepage 
mode con codepage /status 
Typing "/status” is optional. 


For more information about using the mode command to set or display code 
pages, see Appendix E, How to Use Code Pages. 


Notes: 


You can use the following abbreviations with the mode command for code 


page modes: 


Type 
cp 
Ista 
prep 
sel 
ref 


In place of 
codepage 
/status 
prepare 
select 
refresh 


e Ifyou want to print files whenever you start MS-DOS, include mode 
commands in your autoexec.bat or startup.cmd file. 


e Ifyou are using the mode command over a network, do not use the p 
switch for continuous retry. 
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e If you print files every time you start MS-DOS, you may want to include 
mode commands in your autoexec.bat file. See Chapter 4, "Batch 
Processing," for more information on the autoexec.bat file. 


Examples: 


Suppose you want your computer to send its printer output to a serial printer. 
To do this, you need to use the mode command twice. The first mode 
command specifies the asynchronous communication modes, and the second 
mode command redirects the computer’s parallel printer output to the 
asynchronous communication port specified in the first mode command. 


For example, if your serial printer operates at 4800 baud with even parity, and 
if it is connected to the COM1 port (the first serial connection on your 
computer), you would type 


mode com1:48,e,,,p 
mode lptl:=coml: 


If you have redirected parallel printer output from LPT1 to COM1, and then 
decide that you want to print a file using LPT1, type 


mode lptl: 

This command disables any redirection of LPT1. 

Suppose you want your computer to print on a parallel printer that is connected 
parallel to your computer’s second printer port (LPT2). If you want to print 
with 80 characters per line and 8 characters per inch, you would type 
mode lpt2: 80,8 

or 

mode lpt2:,8 

If you want your computer to keep trying to print a file until your printer is 
ready to print it, type 

mode lpt2:80,8,p 


To stop retrying to print, you can press CONTROL-BREAK or type the mode 
command without the p option. 
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More [E] 
Purpose: 


Displays output one screen at a time. 
Syntax: 


more < source 

or 

source , more 

where: 

source is a file or command. 


Comments: 


More is a filter that reads from standard input (from a pipe or redirected file) 
and displays one screen of information at a time. More is commonly used to 
view long files. 

For example, you may use the dir command, the sort command or a filename 
as a source. The more command then pauses and displays the --More-- 
message at the bottom of your screen. 


Press the RETURN key to display another screen of information, then keep 
pressing it until you have read all the data. 


Notes: 


To hold input information until it is displayed, the more command creates a 
temporary file on the disk. If the disk is full or write-protected, more will not 
work. 


See Also: 
For more information about using redirection symbols with commands, see 


Chapter 2, "Using MS-DOS Commands.” 


Examples: 


Suppose you have a long file called clients.new that you want to view on your 
screen. The following command redirects the file through the more command 
to show the file’s contents one screen at a time: 


more < clients.new 
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If you have a long file of customers you could use the more command to view 
it one screen at a time. Suppose this file is called clients.new. To see it, you 
would just type the following command: 


type clients.new ı more 
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Nisfunc [E] 
Purpose: 


Loads country-specific information. 


Syntax: 


nlsfunc[[drive:][path]filename] 
where: 


filename specifies the file containing country-specific information. 


Comments: 


The nlsfunc command supports the use of extended country-specific 
information and code page switching. 


The default value of filename is defined by the country command in your 
config.sys file. If no country command exists in your config.sys file, MS-DOS 
uses the country.sys file in your root directory for country-specific information. 


Examples: 


Suppose you have a file on your disk called newcdpg.sys that contains country- 
specific information. If you want to use the information from that file rather 
than the country.sys file, you would type the following command: 


nlsfunc newcdpg.sys 


To use the default country-specific information found in the country.sys file, 
simply type this command: 


nisfunc 
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Path [1] 
Purpose: 


Sets a command search path. 


Syntax: 


path [drive:][path][;[drive:][path]...] 
or 


path ; 


Comments: 


The path command lets you tell MS-DOS which directories to search for 
external commands—after it searches your working directory. The default 
value is no path. 

For instance, to tell MS-DOS to search the \ user \ pete directory for external 
commands, you would simply type the path command followed by the 
directory name \ user \ pete. Then, until you exit MS-DOS or set another path, 
MS-DOS searches the \ user \ pete directory for external commands. 

You can tell MS-DOS to search more than one path by specifying several paths 
separated by semicolons. If you use the path command without options, it 
prints the current path. And if you use the following command, MS-DOS 
searches only the working directory for external commands: 


path ; 
This path is also called the NUL path. 


Examples: 


The following command tells MS-DOS to search three directories to find 
external commands (the three paths for these directories are \ user \ pete, b:\ 
user \ emily, and \ bin): 

path \user\pete;b:\user\emily;\bin 

MS-DOS searches the paths in the order specified in the path command. 


3.78 MS-DOS User's Reference 


Print [E] 


Purpose: 





Prints a text file on a lineprinter while you are processing other MS-DOS 
commands (usually called background printing). 


Syntax: 


print [/d:device][/b:size}[/u:valuel! )[/m:value2]{/s:timeslice][/q:qsize] 
[/t]{/c]{/p] (drive: ][pathname] 


Comments: 


You can use the print command only if you have an output device, such as a 
printer or a plotter, connected to one of your computer’s serial or parallel ports. 


The following are the switches accepted by the print command: 


Switch Purpose 


/d:device Specifies the print device name. The default device is LPT1. 
Other possible print device names for parallel ports are PRN, 
LPT2, and LPT3. COMx, where x is a number from 1 to 4, 
refers to a serial port. (LPT1 and PRN both refer to the first 
parallel port on your computer.) 


/b: size Sets the size in bytes of the internal buffer. To speed up the 
print command, you increase the value of /b. The minimum 
value of /b is 512, the maximum is 16,386. 

/u:value] Specifies the number of clockticks print will wait for a printer. 
If the printer is not available within the time specified, the job 
will not run. The default for value] is 1. 

/m:value2 Specifies the number of clockticks print can take to print a 
character on the printer. Valid values for value2 range from 1 to 
255. The default is 2. 

/s:timeslice The interval of time to be used by the MS-DOS scheduler for the 
print command. 


/q:qsize 


it 
Ic 


/p 
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Specifies the number of files allowed in the print queue—if you 
want more than 10. The minimum value for the /q switch is 4, 
the maximum, 32, and the default, 10. To change this default 
number of files, you must use the print command without any 
filenames; for example, 


print /q:32 

Deletes all files in the print queue (those files waiting to be 
printed). 

Turns on cancel mode and removes the preceding filename and 
all following filenames from the print queue. 


Tums on print mode and adds the preceding filename and all 
following filenames to the print queue. 


The print command, when used with no options, displays the contents of the 
print queue on your screen without affecting the queue. 


Notes: 


e The /d, /b, /u, /m, /s, and /q switches are allowed only the first time you 
run the print command after starting MS-DOS. 


e Each print queue entry may contain a maximum of 64 characters, 
including the drive name. So you may need to change directories first to 
avoid using extensive pathnames. 


e Some applications have their own print commands. You should use the 
application’s print facility to print files that you create with the 
application. 


Examples: 


The following command empties the print queue for the device named LPT1: 
print /t /d:lptl 
The following command removes the pencil.tst file from the default print 


queue: 


print a:pencil.tst /c 
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The next two commands show how to remove the file pencil.tst from the queue 
and then add the file pen.tst to the queue: 


print pencil.tst /c 
print pen.tst /p 
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Prompt [I] 
Purpose: 


Changes the MS-DOS command prompt. 

Syntax: 

prompt [[text][$character]...] 

Comments: 

This command lets you change the MS-DOS system prompt (for example, A>). 


If, when using the prompt command, you do not type a new value, the prompt 
is set to the default value, which includes the default drive name. 


You can use the characters in the prompt command to create special prompts: 


Type these To get this prompt 


characters 

$q The = character 

$$ The $ character 

$t The current time 

$d The current date 

$p The working directory of the default drive 

$v The version number 

$n The default drive 

$g The > character 

$I The < character 

$b The ; character 

$_ RETURN-LINEFEED 

$e asci code X’1B’ (escape) 

$h Backspace (to erase a character that has been written to the 
prompt line) 

Examples: 


The following example sets the drive prompt to drive:current directory: 


prompt $p 
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The following command sets a two-line prompt that displays the following: 
Time = (current time) 

Date = (current date) 

prompt time = $t$_date = $d 


If your terminal has an ANsI escape sequence driver, you can use escape 
sequences in your prompts. The following command, for example, sets your 
prompt in inverse video mode and returns to video mode for other text: 


prompt Se{7m$n:$e[m 
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Recover [E] (fey) 
Purpose: 


Recovers a file or disk containing bad sectors. 


Syntax: 


recover (drive:)[path]filename 
or 
recover [drive:] 


Comments: 


If the chkdsk command shows that a sector on your disk is bad, you can use 
the recover command to recover the entire disk or just the file containing the 
bad sector. 


The recover command causes MS-DOS to read the file sector by sector and to 
skip the bad sectors. When MS-DOS finds a bad sector, it no longer allocates 
your data to that sector. 


Notes: 


° The recover command does not work on a network from a remote work 
station. 


e Recover doesn’t work on drives used in the subst or join commands. 


Examples: 


To recover a disk in drive A, you would use the following command: 
recover a: 


Suppose you have a file named pencil.ad that has a few bad sectors. To recover 
this file, you would use the following command: 


recover pencil.ad 
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Ren (Rename) [1] 
Purpose: 


Changes the name of a file. 


Syntax: 


rename [drive:}] [path] filename] filename2 
or 

ren [drive:][path| filename] filename2 
where: 


filename] is the old name. 
filename? is the new name. 


Comments: 


The ren command renames all files matching filenamel. However, because you 
cannot rename files across disk drives, the ren command ignores any drive 
name that you specify with filename2. 


You may use wildcards (* or ?) in either filename option, but if you use them in 
filename2, ren will not change the positions of the corresponding character. 


Examples: 


The following command changes the extension of all filenames ending in .txt to 
doc: 


ren *.txt *.doc 

In the next example, ren renames a file named chap/0 (on drive B) to part/0: 
ren b:chapl10 partl10 

The newly renamed file part10 remains on drive B. 
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Replace [E] 
Purpose: 


Updates previous versions of files. 


Syntax: 


replace [drive:]pathnamel [drive:][pathname2] [/a][/p]{/r]{/s][/w] 
where: 


pathname! is the source path and filename. 
pathnamez2 is the target path and filename. 


Comments: 


The replace command performs two functions: 
e It replaces files in the target directory with files in the source directory that 
have the same name. 


e When you specify the /a switch, replace adds files that exist in the source 
directory (but not in the target directory) to the target directory. 


You may use wildcards in source filenames. 
The replace command accepts the following switches: 


Switch Purpose 

la Adds new files to the target directory instead of replacing 
existing ones. You may not use this switch with the /s switch. 

/p Prompts you with the following message before it replaces a 
target file or adds a source file: 
Replace filename? (Y/N) _ 

Ir Replaces read-only files as well as unprotected files. If you do 
not specify this switch, any attempt to replace a read-only file 
causes an error and stops the replace process. 
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Is Searches all subdirectories of the target directory while it 
replaces matching files. This switch is incompatible with the /a 
switch. Replace never searches subdirectories in the source 
path. 


lw Waits for you to insert a disk before beginning to search for 
source files. If you do not specify the /w switch, replace begins 
replacing or adding files immediately. 


If you specify /w but not /a, replace displays the following message: 
Press any key to begin replacing files 


If you specify both the /w and /a switches, replace displays the following 
message: 


Press any key to begin adding file(s) 


As files are replaced or added, replace displays their filenames on the screen. 
At the conclusion of the replace operation, it displays a summary line: 


nnn file(s) added/replaced 
or 
No files added/replaced 


Notes: 


e You cannot use the replace command to update hidden files or system 
files (io.sys and msdos.sys). 
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e Upon completion, replace returns one of the following exit codes: 


Code Function 

Command successful 
Command line error 
File not found 

Path not found 
Access denied 


oM WN KS O 


Insufficient memory 
15 Invalid drive 
Other Standard MS-DOS error 


You can test for these codes by using the errorlevel condition of the batch 
processing if command. 


Examples: 


Suppose various directories on your hard disk, drive C, contain files named 
phones.cli that contain client names and phone numbers. To update these files 
and replace them with the latest version of the phones.cli file on the disk in 
drive A, you would type the following command: 


replace a:\phones.cli c:\ /s 
This command replaces every file on drive C that is named phones.cli with the 
file phones.cli from the root directory on drive A. 


Suppose you want to add some new printer device drivers to a directory called 
c: \mstools, which already contains several printer driver files for a word 
processor. To do this, you would type the following: 


replace a:*.prd c:\mstools /a 


This command searches the default directory of drive A for any files that have 
the extension .prd (that don’t currently exist in the \ mstools directory on drive 
C) and then adds these files to c:\ mstools. 
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Restore [E] 
Purpose: 


Restores files that were backed up using the backup program. 


Syntax: 


restore drivel: [drive2:][pathname] 


[/s][/p][/b:date][/a:date][/e:time][/L:time)[/m] [/n] 
where: 


drivel contains the backed-up files. 
drive2 is the target drive. 
pathname identifies the file(s) you want to restore. 


Comments: 


The restore command can restore files from similar or dissimilar disk types. 
The restore command accepts the following switches: 


Switch Purpose 

Is Restores subdirectories also. 

/p Prompts for permission to restore any files matching the file 
specification that are read-only or that have changed since the 
last backup. 

/b:date Restores only those files last modified on or before date. 

/a:date Restores only those files last modified on or after date. 

/e:time Restores only those files last modified at or earlier than time. 

/L:time Restores only those files last modified at or later than time. 

/m Restores only those files modified since the last backup. 

/n Restores only those files that no longer exist on the target disk. 


Once MS-DOS has restored the file, use the dir or type command to make sure 
that the file was restored properly. 
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Notes: 


e Restore cannot restore the system files. Use the sys command to restore 
these files. 


e The MS-DOS 3.3 restore command will restore files backed up with 
either the MS-DOS 3.3 backup command, or an earlier version of 


backup. 
e Upon completion, restore returns one of the following exit codes: 


Code Function 


0 Normal completion 

1 No files were found to restore 
3 Terminated by user 

4 Terminated due to error 


You can test for these codes by using the errorlevel condition of the if 
batch processing command. 


Examples: 


To restore the file invest.mnt from the backup disk in drive A to the \ irsharpe 
directory on drive C, type the following: 

restore a: c:\irsharpe\invest.mnt 

Press the RETURN key to let MS-DOS know that the backup disk is in drive A. 
Then once MS-DOS has restored the file, use the dir or type command to make 
sure that the file was restored properly. 
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Rmdir (rd) [I] 
Purpose: 


Removes a directory from a multilevel directory structure. 


Syntax: 


rmdir [drive:]path 
or 
rd [drive:|path 


Comments: 


Rmdir removes a directory that is empty except for the "." and ".." symbols. 
These two symbols refer to the directory itself and its parent directory, 
respectively. Before you can remove a directory entirely, you must delete its 
files and subdirectories. 


Notes: 


You cannot remove a directory that contains hidden files. In addition to MS- 
DOS, which has some hidden files, certain application programs also create 
their own hidden files. 


Examples: 


Suppose you want to remove a directory named \ user \ pete. You would follow 
these steps: 


1. To ensure that the directory is empty, type the following: 
dir \user\pete 


2. Then, from any directory except the one you want to remove, type the 
following command: 


rmdir \user\pete 


Remember that if you are working in the same directory that you are trying to 
remove, you'll receive the following error message: 


Invalid path, not directory, or directory not empty. 
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Select [E] 
Purpose: 


Installs MS-DOS on a new floppy with desired country-specific information 
and keyboard layout. 


Syntax: 


select[[drivel:] [drive2:][path]] [yyy][x] 
where: 


drivel is the source drive. 
drive2 is the target drive. 


Comments: 


The select command lets you install MS-DOS on a new disk along with 
country-specific information (such as date and time formats, and collating 
sequence) for a selected country. 


The select command does the following: 

e Formats the target disk. 

e Creates both the config.sys and autoexec.bat files on the new disk. 

e Copies the contents of the source disk, track by track, to the source disk. 


The source drive may be either drive A or drive B. The default source drive is 
drive A. The default target drive is drive B. 


If you choose a hard disk as the target, MS-DOS will prompt you to type the 
correct internal label for that disk. If you type the wrong label, select ends. If 
you type the correct label, select displays a second warning like the following: 


WARNING, ALL DATA ON NON-REMOVABLE DISK 
DRIVE D: WILL BE LOST! 
Proceed with Format (Y/N) ? 


If you type N (for No), select ends. If you type Y (for Yes), the target disk is 
formatted. 
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You can use the following options with the MS-DOS select command: 


Option Purpose 

yyy Specifies the country code. MSDOS gathers country-specific 
information such as time and date formats from the country.sys 
file for the country code specified. 


xx Specifies the keyboard code for the keyboard layout used. For a 
list of valid keyboard codes, see the keyb command. 


Examples: 


Suppose you want to create a new MS-DOS disk that included the country- 
specific information and keyboard layout for Germany. With your source disk 
in drive B and your target disk in drive A, you would type the following: 


select b: a: 049 gr 

MS-DOS displays this message: 

SELECT is used to install DOS the first 
time. SELECT erases everything on the 


specified target and then installs DOS. 

Do you want to continue (Y/N)? Y 

If the disk in drive A contains any data files, they will be erased, unless you 
type N (for No). If the disk is blank, or reusable, type Y (for Yes) and press the 
RETURN key. 

Then MS-DOS prompts you to insert a new disk in drive A. After it formats the 
disk, MS-DOS copies files from the source disk B to the target disk A. 
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Set [I] 
Purpose: 


Sets one string of characters in the environment equal to another string for later 
use in programs. 


Syntax: 


set [string=[string]] 


Comments: 


You should use the set command only if you want to set values for programs 
you have written. 


When MS-DOS recognizes a set command, it inserts the given string and its 
equivalent into a part of memory reserved for the environment. If the string 
already exists in the environment, it is replaced with the new setting. 


If you specify just the first string, set removes any previous setting of that 
string from the environment. Or if you use the set command without options, 
MS-DOS displays the current environment settings. 


When batch processing, you can also use the set command to define your 
replaceable parameters by name instead of by number. For example, if your 
batch file contains the statement type %file%, you could use the set command 
to set the name that MS-DOS will use for that variable. In the following 
command, for example, set stores a value for MS-DOS to replace the %file% 
parameter with the filename taxes.86: 

set file=taxes. 86 

To change the replaceable parameter names, you don’t need to edit each batch 
file. Note also that when you use text (instead of a number) as a replaceable 
parameter, the name must be ended by a percent sign. 

The set command is especially useful in the autoexec.bat file, because it lets 
you automatically set strings or parameters when you start MS-DOS. See 
Chapter 4, Batch Processing, for more information about the autoexec.bat file. 
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Examples: 


The following command sets the string “include” to c:Nnc until you change it 
with another set command: 


set include=c:\inc 
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Share [E] 
Purpose: 

Installs file sharing and locking. 

Syntax: 


share [/f:space][/L:locks] 


Comments: 


You can see the share command only when networking is active. If you want 
to install shared files, you can include the share command in your autoexec.bat 
file. To learn more about shared files, see the Microsoft Networks 1.0 
Manager's Guide. 


The share command accepts the following switches: 


Switch Purpose 

/f:space Allocates file space (in bytes) for the MS-DOS storage area used 
to record file sharing information. The default value for the /f 
switch is 2048. Note that each open file requires enough space 
for the length of the full filename plus 11 bytes, since an average 
pathname is 20 bytes in length. 

[L:locks Allocates the number of locks you want to allow. The default 
value for the /L switch is 20. 

Once you have used the share command in an MS-DOS session, all read and 

write requests are checked by MS-DOS. 


Example: 


The following example loads file sharing and uses the default values for the /f 
and /L switches: 


share 
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Sort [E] 
Purpose: 


Reads input, sorts the data, then writes the sorted data to your screen, to a file, 
or to another device. 


Syntax: 


[source] | sort [/r][/+n] 
or 

sort [/r][/+n] < source 
where: 


source is a filename or command. 


Comments: 


The sort command is a filter program that lets you alphabetize a file according 
to the character in a certain column. The sort program uses the collating 
sequence table, based on the country code and code page settings. 


The | and < redirection symbols direct data through the sort utility from source. 
For example, you may use the dir command or a filename as a source. You 
may use the more command or a filename as a destination. 


The sort command accepts the following switches: 


Switch Purpose 
/r Reverses the sort; that is, sorts from Z to A, and then from 9 to 0. 
/+n Sorts the file according to the character in column n, where n is some 


number. If you do not specify this switch, the sort command sorts the 
file according to the character in the first column. 


Unless you specify a source, sort acts as a filter and accepts input from the MS- 
DOS standard input (usually from the keyboard, from a pipe, or redirected from 
a file). 
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Notes: 


e Sort does not distinguish between uppercase and lowercase letters. 


e Characters above ascii code 127 are sorted based on information found in 
the country.sys file, or in an alternate file specified by the country 
command in your config.sys file. 

e For more information about using redirection symbols with commands, 
see Chapter 2, "About Commands.” 


Examples: 


The following command reads the file expenses.txt, sorts it in reverse order, 
and displays it on your screen: 

sort /r < expenses.txt 

The following command pipes the output of the dir command to the sort filter. 
This filter sorts the directory listing starting with column 14 (the column in the 
directory listing that contains the file size) and sends the output to the screen. 
The result is a directory, sorted by file size: 

dir ; sort /+14 

The following command does the same thing as the previous one, except that 
the more filter gives you a chance to read the sorted directory one screen at a 
time: 


dir ; sort /+14 ; more 
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Subst [E] Ae) 


Purpose: 


Substitutes a string for a path. 


Syntax: 


subst [drive: drive:path] 
or 
subst drive: /d 


Comments: 


The subst command lets you associate a path with a drive letter. This drive 
letter then represents a virtual drive because you can use the drive letter in 
commands as if it represented an actual physical drive. 

When MS-DOS finds a command that uses a virtual drive, it replaces the drive 
letter with the path and treats that new drive letter as though it belonged to a 
physical drive. 

If you type the subst command without options, MS-DOS displays the names 
of the virtual drives in effect. 


Use the /d switch to delete a virtual drive. 
Notes: 


The following commands do not work on drives used in the subst command (or 
the join command): 


chkdsk label 
diskcopy recover 
fdisk sys 
format 

Examples: 


The following command creates a virtual drive, drive Z, for the pathname b:\ 
user \ betty \ forms: 


subst z: b:\user\betty\forms 
Note This example assumes that you have included the line, lastdrive=z, in 
your config.sys file. 


Now, instead of typing the full pathname, you can get to this directory by 
simply typing the name of the virtual drive: 


Z: 
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se ë E6 


Purpose: 


Transfers the MS-DOS system files from the disk in the default drive to the 
disk in the specified drive. 


Syntax: 


sys drive: 
Comments: 


The sys command updates your system files on a disk. You must type a drive 
letter following the sys command. 


Notes: 


e The transferred files are copied in the following order: 
io.sys 
msdos.sys 


Io.sys and msdos.sys are both hidden files that do not appear when you 
type the dir command. 


e Sys does not transfer the command.com file (the command processor). So 
to transfer command.com to the target disk, you must use the copy 
command. 


e MS-DOS system files are no longer required to be contiguous. This means 
that you do not have to reformat your disk when you want to copy a new 
version of MS-DOS on a disk containing system files for MS-DOS 
version 3.2 or earlier. 


e Sys doesn’t work on drives involved with subst or join commands. 
e Sys does not work on a network. 


Examples: 


If you want to copy the MS-DOS system files from your working directory to a 
disk in drive A, you would type 


sys a: 


3.100 MS-DOS User's Reference 


Time [E] 
Purpose: 


Allows you to enter or change the time known to the system. 


Syntax: 


time [hours:minutes|:seconds [.hundredths]]] 


Comments: 


MS-DOS keeps track of time in a 24-hour format, and uses the time 
information to update the directory whenever you create or change a file. 


The time command without options displays the current time, and gives you an 
opportunity to change it: 

Current time is hh:mm:ss.cc 

Enter new time: _ 

If you do not want to change the time shown simply press the RETURN key. 


If you do want to change the time, type in a new value in the 24-hour clock 
format. The following are valid values: 


hours = 0-23 
minutes = 0-59 
seconds = 0-59 


hundredths = 0-99 


Separate these elements (seconds and hundredths of seconds are optional) with 
the separator defined in the country-dependent information file. For the United 
States, use a colon (:). 


You can also type the new time directly on the command line. If you do not 
type a valid time, MS-DOS displays the following message and then waits for 
you to type a valid time: 

Invalid time 

Enter new time: _ 


Notes: 


e You can change the time command format by changing the country 
command in the config.sys file. For more information, see Appendix B, 
“How to Configure Your System.” 
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e The time command sets your computer’s internal clock. 
e You cannot specify a drive for this command. 


Examples: 


To reset the time of day on your computer’s clock, you can type the time 
command by itself and MS-DOS will prompt you for the correct time. Or you 
can include the correct time when you type the command. For example, if you 
want to set your computer’s clock at 1:36 p.m., you could type the following 
command: 


time 13:36 
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Tree [E] 
Purpose: 


Displays the path (and, optionally, lists the contents) of each directory and 
subdirectory on the given drive. 


Syntax: 
tree [drive:] [/f] 


Comments: 


The tree command lists the full path of each directory, along with the names of 
their subdirectories. 


The /f switch displays the names of the files in each directory. 


Notes: 


Another way to list all of the subdirectories in your working directory is to type 
dir *, This will also report all files that have no file extensions. Directories are 
identified with the label "<DIR>." 


Examples: 


If you want to see names of all directories and subdirectories on your computer, 
simply type 
tree 


If you also want to see, one screen at a time, the files in all the directories on 
drive C, you could type 


tree c: /f | more 
To print that same list on a printer, use listing the following command: 
tree c: /f > prn 
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Type [I] 
Purpose: 


Displays the contents of a text file on the screen. 


Syntax: 


type [drive:] filename 


Comments: 


You can use the type command to view a text file without modifying it. (Use 
dir to find the name of a file and Edlin to change the contents of a file.) 


Note that when you use type to display a file that contains tabs, all the tabs are 
expanded to the current setting for tabs (generally eight spaces wide). Also, if 
you try to display a binary file or a file created by an application program, you 
may see strange characters on the screen, including bells, formfeeds, and 
escape sequence symbols. 


Examples: 


If you want to display the contents of a file called holiday.mar, you would type 
the following command: 


type holiday.mar 


If the contents of the file you wish to display are fairly long, you could use a 
command like this to display the file’s contents one screen at a time: 


type holiday.88 ; more 
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Ver [I] 
Purpose: 


Prints the MS-DOS version number. 


Syntax: 


ver 


Comment: 


If you want to know what version of MS-DOS you are using, you simply type 
the ver command. The version number will then be displayed on your screen. 


Example: 


When you type the ver command, the following message is displayed: 
MS-DOS Version 3.30 
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Verify [I] 
Purpose: 


Turns the verify switch on or off when writing to a disk. 


Syntax: 


verify [on] 
or 
verify [off] 


Comments: 


You can use this command to verify that your files are written correctly to the 
disk (no bad sectors, for example). MS-DOS verifies the data as it is written to 
a disk. You will receive an error message only if MS-DOS is unable to 
successfully write your data to a disk. 


Notes: 


This command has the same purpose as the /v switch in the copy command. 


Examples: 


If you want to know the current setting of verify, use the verify command 
without an option: 


verify 


Verify on remains in effect until a program changes it, or until you type the 
following: 


verify off 
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Vol [I] 


Purpose: 





Displays the disk volume label or volume identification, if it exists. 


Syntax: 


vol [drive:] 


Comments: 


This command displays the volume label of the disk in a specific drive. If you 
do not type a drive letter, MS-DOS displays the volume label of the disk in the 
default drive. 


Notes: 


e You cannot specify a drive name before this command. For example, if 
you typed b:vol c:, MS-DOS would display an error message because of 
the reference to drive B. MS-DOS assumes that this command resides on 
the drive you are working from. 


è For more information about how MS-DOS uses volume labels, see the 
label and format commands in this chapter. 


Examples: 


If you want to find out what the volume label is for the disk in drive A, you 
would type the following: 


vol a: 
If the volume label is "DOS 3-3" MS-DOS responds by displaying the message 
Volume in drive A is DOS 3-3 
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Xcopy [E] 
Purpose: 


Copies files and directories, including lower level directories, if they exist. 


Syntax: 


xcopy [drive:]pathname [drive:][pathname] [/a][/d:date] 
[/e][/m}[/p]l/s][/v][/w] 

or 

xcopy drive:[pathname] [drive:][pathname] [/a][/d:date][/e][/m][/p][/s][/v][/w] 


Comments: 


The first set of drive: and pathname parameters specify the source file or 
directory that you want to copy. The second set names the target. You must 
include at least one of the source parameters. If you omit the target parameters, 
xcopy assumes you want to copy the files to the default directory. 


If you do not specify the pathname option, xcopy uses the default directory 
with the default filename, *.*. 


The xcopy command accepts the following switches: 


Switch Purpose 


la Copies source files that have their archive bit set. Does not 
modify the archive bit of the source file. For information on how 
to set the archive attribute, see the attrib command. 


/d:date Copies source files modified on or after the specified date. Note 
that the date format may vary depending on the country code 
that you are using. For more information, see the date 


command. 

le Copies any subdirectories,even if they are empty. You must use 
this switch with the /s switch. 

/m Same as the /a switch, but after copying a file, it turns off the 


archive bit in the source file. For information on how to set the 
archive attribute, see the attrib command. 
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/p 


/s 


Iv 


Notes: 


Prompts you with "(Y/N?),” allowing you to confirm whether 
you want to create each target file. 

Copies directories and lower level subdirectories, unless they are 
empty. If you omit this switch, xcopy works within a single 
directory. 

Causes xcopy to verify each file as it is written to the target to 
make sure that the target files are identical to the source files. 


Causes xcopy to wait before it starts copying files. Xcopy 
displays the following message: 

Press any key when ready to start copying 
files 


You must press a key to continue, or press CONTROL-C to abort the 
xcopy command. 


If you have a disk that contains files in subdirectories and you want to 
copy it to a target disk that has a different format, you should use the 
xcopy command rather than diskcopy. The diskcopy command copies 
disks track-by-track, it requires your source and target disks to have the 
same format. 


If xcopy encounters an error, it returns one of the following exit codes: 


Code 
0 


1 
2 
4 


Function 

Copy without error 

No files found to copy 

CONTROL-C entered by user to terminate xcopy 


Initialization error 
There is not enough memory—invalid drive or command line 
syntax, file not found, or path not found. 


Int 24 error occurred 
The user aborted from INT 24 error reading or writing disk. 


You can test for these codes by using the errorlevel condition of the batch 
processing if command. 
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Examples: 


The following example copies all the files and subdirectories (including any 
empty subdirectories) on the disk in drive A to the disk in drive B: 


xcopy a: b: /s /e 


The xcopy command may prompt you to specify whether the target is a file or a 
directory. If you don’t want to receive this prompt, type the following 
command: 


copy /b xcopy.exe mcopy.exe 


This example creates a new command called mcopy. Now you can use the 
mcopy command the same way you use the xcopy command, but mcopy 
automatically determines whether the target is a file or a directory. 


Mcopy uses the following rules for copying files: 
e Ifthe source is a directory, the target is a directory. 
e Ifthe source includes multiple files, the target is a directory. 


e [Ifyou append a backslash (\) to the end of the target name, the target is a 
directory. For example, the following command creates the directory 
a:\workers if it doesn’t already exist, and copies the file payroll to it: 


xcopy payroll a:\workers\ 


4 Batch Processing 


In this chapter, you will learn 

How to create a batch file 

How an autoexec.bat file works 
e How to use replaceable parameters in a batch file 
e How to run a batch file 


Note If you are not writing batch programs you do not need to read this 
chapter. 


Why Use Batch Files? 


You may often find yourself repeatedly typing the same sequence of commands 
to perform some common task. With MS-DOS you can put this command 
sequence into a special file called a batch file, and then run the whole sequence 
of commands by simply typing the name of the batch file. Note that you don’t 
need to type the batch file’s extension, even though all your batch files must 
include the .bat extension in their filenames. 


MS-DOS performs these "batches" of your commands just as if you had typed 
them from the keyboard. This is called batch processing. By using a batch file, 
you only have to remember to type one command, instead of several. In effect, 
you use batch files to create personalized commands. 


How to Create Batch Files 


You can create a batch file by using Edlin, the MS-DOS line editor, by using 
the copy command, or by using a word processor that saves files as ascu text. If 
you want to create files with Edlin, you should refer to Chapter 6 for more 
information. The examples in this chapter show you how to use the copy 
command to create batch files. 
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Suppose, for example, that you want to create a batch file to format and check a 
new disk. To do this you simply follow these steps: 


1. 


First, type the following: 

copy con checknew.bat 

Press RETURN. This command tells MS-DOS to copy the information from 
the console (keyboard) to the file checknew.bat. 

Next, type the following lines, pressing the RETURN key after each: 

rem This is a file to format and 

rem check new disks. 

rem It is named CHECKNEW. BAT. 

pause Insert new disk in drive B: 


format b: /v 
chkdsk b: 


After the last line, press conrroL-z and then press RETURN to save the batch 
file. MS-DOS displays the message "1 File(s) copied” to show that it 
created the file. 


Now, to execute the file, simply type the following command: 


checknew 


The result is the same as if the lines in the .bat file were typed from the 
keyboard as individual commands. 


About Batch Processing 


Here are a few things you should know before you run a batch process with 
MS-DOS: 


You must name each batch file with an extension of .bat. 
To execute a batch file, you type only its filename and not the extension. 


If you press conTRoL-c while the batch file is running, MS-DOS asks you 
to confirm that you want to terminate the batch process. 


If you remove the disk that contains a batch file being run, MS-DOS 
prompts you to reinsert the disk so that it can continue processing the file. 
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ə You can specify the name of another batch file as the last command in a 
batch file. This feature allows you to call one batch file from another when 


the first has finished. 

e Youcan use any of the redirection symbols (< > >>) in a batch file. For 
more information on using these symbols, see Chapter 2, "About 
Commands.” 


e You may use an @ character at the front of a command line in a batch file 
to prevent that line from echoing. 


e Youcan use the pipe symbol (!) in a batch file. 


e Setting the directory or drive affects every subsequent command in the 
batch file. 


e Setting environment strings also affects every subsequent command in the 
batch file. 


Note If you have more than one external command with the same name, MS- 
DOS will run only one of them, according to the following order of precedence: 
com, .exe, .bat. 


Suppose, for example, that your disk includes the files format.exe and 
format.bat. If you were to type the external command format, MS-DOS would 
always run the program format.exe first. In order to run the batch file 
format.bat, you would have to place it in a separate directory and give a path 
along with the external command. 


For example, if your format.bat file is in a directory named \commands\batch 
and you want to run it, you would type the following: 


\commands \batch\format 


The Autoexec.bat File 


The autoexec.bat file lets you run programs automatically when you start MS- 
DOS. This can be useful when you want to run a specific application under 
MS-DOS, and when you want MS-DOS to execute a batch program each time 
you start your computer. By using an autoexec.bat file you can avoid loading 
two separate disks just to perform these tasks. 


When you start your computer, MS-DOS searches the root directory of the 
default disk drive for a file named autoexec.bat. If it finds the autoexec.bat file, 
MS-DOS immediately processes it, bypassing the date and time prompts. If 
MS-DOS does not find an autoexec.bat file, then the date and time prompts 
appear automatically. 
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Hint MS-DOS does not prompt you for a current date and time unless you 
include date and time commands in your autoexec.bat file. 
It’s a good idea to add these two commands to your autoexec.bat file, since 


MS-DOS uses this information to keep your directory current. See Chapter 3, 
"MS-DOS Commands," for more information on the date and time commands. 


Batch Processing 


The following figure shows what happens when you start MS-DOS: 
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processor executes 
the “autoexec.bat” file 
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How to Create an Autoexec.bat File 


There are many things you can do with an autoexec.bat file to help you use 
MS-DOS more efficiently. For instance, you will probably want to set the time 
and date, your path, and any other options that you plan to use on a regular 
basis. 


Note When you create your autoexec.bat file, you must put it in the root 
directory of your MS-DOS disk. 


If, for example, you want to automatically load cw-Basıc and run a program 
called menu each time you start MS-DOS, you could create an autoexec.bat 
file as follows: 


1. Type the following command and then press RETURN: 
copy con autoexec.bat 
This command tells MS-DOS to copy what you type from the keyboard 


into the autoexec.bat file. Note that you must put the autoexec.bat file in 
the root directory of your MS-DOS disk. 


2. Now type the following lines: 


date 

time 
path=c:\;c:\bin;a:\ 
prompt [Sp] 

cls 

gwbasici menu 


3. After the last line, press conrRoL-z and press RETURN to copy these lines 
into the autoexec.bat file. 


4. The menu program will now run automatically whenever you start MS- 
DOS. 


Once your autoexec.bat file is set up as in this example, it will perform the 
following actions when you start MS-DOS: it will ask you to enter the date and 
time; it will set your command search path; and it will set your prompt to 
display the default drive and director. 


Finally, the autoexec.bat file will clear the screen and tell MS-DOS to load cw- 
Basic and run the menu program. To run your own Gw-BASIC program, type its 
name in place of menu in the example. In addition to Gw-Basic programs, you 
can also put any MS-DOS command or series of commands in the autoexec.bat 
file. 
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How to Create a Batch File 
with Replaceable Parameters 


There may be times when you want to create a program and run it with 
different sets of data. These data may be stored in various MS-DOS files. 


With MS-DOS, you can create a batch (.bat) file with replaceable (dummy) 
parameters, where a parameter is a command option that you define. These 
parameters, named %0-%9, hold the places for the values that you supply when 
you give the batch command. 


Replaceable parameters make batch files more flexible and easy to use. For 
example, you can create a batch file called sorter.bat that sorts a file containing 
a specific sequence of characters or strings. Each time you run the sorter batch 
file, you tell MS-DOS which string you want, which file to search to find that 
string, and which temporary file to use for sorting. Sorter would then print the 
resulting list on the printer. 
1. To create the sorter.bat file, type the following command and then press 
the RETURN key: 
copy con sorter.bat 
2. Now type the following lines: 
type %2 ; find "%1" > %3 
type %3 | sort > prn 
del %3 
3. To save the batch file, press conTRoL-z and then RETURN. The batch file 
sorter .bat now consists of three command lines and is on the disk in the 
default drive. 
When you execute the file, MS-DOS sequentially replaces %1, %2, and %3 
with the parameters you supply. If you use the dummy parameter %0, MS-DOS 
always replaces it with the drive name (if specified) and the filename of the 
batch file (for example, sorter). 
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Notes 


e You can specify up to ten replaceable parameters (%0-%9). If you want to 
specify more than ten, refer to the shift command later in this chapter. 


e Ifyou use the percent sign as part of a filename within a batch file, you 
must type it twice. For example, to specify the file abc%.exe , you must 
type it as abc%%.exe in the batch file. 


How to Use Named Parameters 
in a Batch File 


In addition to the ten, numeric replaceable parameters, you can use named 
parameters in batch files. Named parameters allow you to define your 
replaceable parameters by name instead of by number. When referenced in a 
file the name of a replaceable parameter is placed between two percent signs. 


Named parameters differ from replaceable parameters in that you do not 
specify their values on the command line. Instead, MS-DOS retrieves the value 
of each named parameter from its environment. 


You can use the MS-DOS set command to set the value of a named parameter 
before you run your batch file, or you can include the set command in your 
batch file. 


For example, suppose that you want to create a batch file called mydel.bat, that 
moves a file you want to delete into a separate directory. You might want to use 
this method to make sure that you don’t delete files accidentally from an 
important directory. 


The file mydel.bat might contain the following lines: 


echo off 

echo Before you use this batch file, you must 
echo specify the directory by typing the 
echo following command at the MS-DOS prompt: 
echo set deldir=directory 

echo Press Control-C to exit if you haven’t 
echo set deldir or if deldir does not exist. 
pause 

copy %1 %tdeldir% 

del %1 

dir /w tdeldir% 

echo All done. 
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For this mydel.bat file to work, you must create a directory named deleted. The 
following command line sets the directory name to deleted: 


set deldir=\deleted 
Now, to move the file report23 jun to the deleted directory, type the following: 
mydel report23. jun 


The batch file automatically replaces the %deldir% parameter with the 
directory named deleted. 


You may find named parameters easier to use than replaceable parameters 
because you won’t have to include as much information on the command line. 
For example, with mydel.bat, you don’t have to type the directory name on the 
command line, yet you can change the name of the directory without having to 
edit the batch file. 


How to Run a Batch File 


To run the batch file sorter.bat, type the batch filename followed by the 
parameters that you want MS-DOS to substitute for %1, %2, and %3. 


Suppose that on the disk in drive A you have a file that lists your customers’ 
names and regions. The file might look something like this: 


Shores, Betty north 
Moynihan, Ann south 
Kraig, Heidy north 
Martin, Pete east 

Lennon, Patrick south 
Pai, Fernando north 
Evans, Rick west 

Moss, Melissa north 


If you want to print an alphabetical list of the customers in the north, you can 
run the sorter batch file, with the appropriate parameters, by typing the 
following command and then pressing the RETURN key: 


sorter north a:customer temp.fil 
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The output on the printer should look like this: 


Kraig, Heidy north 
Moss, Melissa north 
Pai, Fernando north 
Shores, Betty north 


The following table shows how MS-DOS replaces each of the parameters in the 
previous example: 


Batch filename (%0) sorter 
Parameterl (%1) north 
Parameter2 ($2) a:customer 
Parameter3 (%3) temp.fil 


The result is the same as if you had typed each of the commands in sorter with 
its parameters, as follows: 

type a:customer ; find "north" > temp.fil 

type temp.fil |; sort > prn 

del temp.fil 

Using the batch file, however, saves typing time and is much easier to 
remember. 


How to Use Temporary Files 


When using batch files, you may often want to use a temporary file to hold 
your work. You could use the same name each time you wanted to use a 
temporary file. 

However, if you are using more than one batch file that uses the same 
temporary file, you might lose the contents of this temporary file. To avoid this 
problem, you should use a replaceable parameter to specify the name of the 
temporary file. Then each time you run the batch file, you’ll be able to 
substitute a unique filename and you won’t have to worry about information 
from one batch file getting into another. 


It’s also a good idea to delete temporary files once you finish using them. 
Otherwise, these files would eventually take up all the space on your disk. 
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Batch Processing Commands 


Now that you have seen some of the capabilities of batch files, in this section 
you'll find out how to add power and flexibility to your batch programs by 
using batch processing commands. The following table lists these batch 
commands and describes what they do: 


Command What it does 


call Calls one batch file from another without ending itself. 

echo Tums the batch file echo feature on or off, or displays the 
current setting. 

for Performs a command for a set of files. 

goto Processes commands starting with the line after the specified 
label. 

if Performs a command if a condition is met. 

pause Suspends execution of a batch file. 

rem Displays a comment in a batch file. 

shift Increases the number of replaceable parameters in a batch 
process. 


Batch commands are also internal commands, so each one is marked with the 
internal command icon (the boxed letter I) used in Chapter 3, "MS-DOS 
Commands." 
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Call [I] 


Purpose: 


Calls one batch file from another without ending itself. 


Syntax: 


call [drive:][path] batchfile [argument] 
where: 


batchfile is the batch file you want to call. 
argument is the command in this batch file that will be run following batchfile. 


Comments: 


The call command is used within one batch file to call another one. Batchfile 
must have a filename extension of.bat. 


When batchfile terminates, the calling batch file resumes running at argument. 
If argument is omitted, the calling batch file resumes running at the command 
immediately following the call command. 


Notes: 


e Donot use pipes and redirection symbols with the call command. 


e A batch file can make a recursive call to itself, but there should be a 
termination condition that is eventually met. 


Examples: 


To run the checknew.bat file from another batch file, you would use the 
following command within the first batch file: 


call checknew 
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Echo [I] 
Purpose: 


Turns the batch echo feature on and off. 


Syntax: 


echo [on] 

or 

echo [off] 

or 

echo [message] 


Comments: 


Normally, commands in a batch file are displayed ("echoed") on the screen 
when they are received by MS-DOS. You can tum off this feature by using the 
off option with the echo command. Similarly, you can turn the echo feature 
back on by using the on option with echo. 


If you do not specify on or off, echo displays the current setting. 


The command, echo message (where message is a line of text), is only useful if 
echo is off and if you are using a batch file. If, in your batch file, you type the 
echo command followed by a message, you can print messages on your screen. 
You can also put several echo message commands in your batch file to display 
a message that is several lines in length. 


An "@" character placed in front of a command line in a batch file prevents 
that line from echoing. 


Examples: 


The following is an example of a batch file message of more than one line: 


echo off 

echo This batch file 
echo formats and checks 
echo new disks. 


If you want to turn echo off, and do not want the command itself to be echoed, 
include the @ character before the command line: 


@echo off 
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For [I] 
Purpose: 


Performs a command for a set of files. 


Syntax: 


for %%c in set do command 
(for batch processing) 


for %c in set do command 
(for interactive processing) 


Comments: 


To avoid confusion with the %0-%9 batch parameters, the variable c can be any 
character except 0,1,2,3,...,9. 
Set is ( item* ) 


This command sequentially sets the %%c variable to each member of set, and 
uses the variable to evaluate command. If a member of set is an expression 
involving a wildcard (* or ?), then the variable is set to each matching ifem 
from the disk. In this case, only one such item is in set, so the command ignores 
any item other than the first. 


Examples: 


The following example assigns the variable %f to any files ending with *.asm 
in the working directory: 
for $f in ( *.asm ) do masm %%f 


It then executes a command of the following form: 
masm filename 


Filename could be any one of the following: 


invoice.asm 

receipts.asm 

taxes.asm 

The following example assigns the variable %%f to the files named report, 
memo, and address; it then deletes each of these files: 


for %%f in (report memo address) do del %%f 
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You must use two percent signs (%%) so that one will remain after the batch 
parameter (%0-%9) processing is complete. If you had only %f, instead of 
%%of, then the batch parameter processor would see the %, look at f, decide that 
%f was an error (a bad parameter reference), and throw out the %f so that the 
for command would never see it. 


Note that if you are using the for command outside of a batch file, you should 
use only one percent sign. 
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Goto [I] 
Purpose: 


Processes commands starting with the line after the specified label. 


Syntax: 


goto [;]label 


Comments: 


Goto lets you take commands from the batch file beginning with the line after 
the label, where a label is defined as the characters following goto. This label 
may include spaces, but not other separators, such as semicolons or equal signs. 
If your batch file does not contain the label, the batch process terminates. 


Note Any line in a batch file that starts with a colon (:) is ignored during batch 
processing. 


Examples: 


The following example sends the program processor to the label named end — 
only if no errors occur when you format the disk in drive A: 

: begin 

echo off 

format a: /s 

if errorlevel 0 goto end 

echo An error occurred during formatting. 

:end 

echo End of batch file. 
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lf T 
Purpose: 


Performs a command based on the result of a condition. 


Syntax: 


if [not] errorlevel number command 
or 

if [not] string] = = string2 command 
or 

if [not] exist filename command 


Comments: 


The if statement allows conditional execution of commands. When the 
condition is true, MS-DOS executes the command, otherwise, it ignores the 
command. 


The conditions are described as follows: 


Condition Description 


errorlevel number True if, and only if, the previous program executed by 
command.com had an exit code equal to, or greater 
than, number. (When a program finishes, it returns an 
exit code via MS-DOS.) You can use this condition to 
perform other tasks that are based on the previous 
program's exit code. 

string] == string2 True if, and only if, string] and string2 are identical 
after parameter substitution. Strings may not contain 
separators, such as commas, semicolons, equal signs, 
or spaces. 


exist filename True if, and only if, filename exits. 


If you specify the not parameter, MS-DOS executes the command when the 
condition is false. 
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Notes: 


For more information about exit codes returned by an MS-DOS command, see 
the specific command in Chapter 3, "MS-DOS Commands.” 


Examples: 


The following example prints the message "can’t find datafile” if the file 
product.dat does not exist on the disk: 


if not exist product.dat echo can’t find datafile 


The following example sends the program processor to the label named end — 
only if no errors occur when you format the disk in drive A. 

:begin 

echo off 

format a: /s 

if errorlevel 0 goto end 

echo An error occurred during formatting. 

zend 

echo End of batch file. 
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Pause [I] 
Purpose: 


Suspends execution of a batch file. 


Syntax: 


pause [comment] 


Comments: 


When a batch file is running, you may need to change disks or perform some 
other action. The pause command suspends execution of the batch file until 
you press any key, unless you press the conTRoL-c key sequence. 


When the command processor encounters pause, it prints the following 
message: 

Strike a key when ready ... 

If you press controL-c, MS-DOS displays the following message: 
Terminate batch job (Y/N)? 


If you type Y (for Yes) in response to this prompt, the batch file ends and 
control returns to the operating system. Therefore, you can use pause to divide 
a batch file into pieces that allow you to end the batch command file at any 
intermediate point. 

The comment parameter is useful when you want to display a special message. 
Unless echo is off, pause displays this comment before the "Strike a key” 
message. 


Note The pause and comment line of your batch file will not appear if echo is 
off. 


Examples: 


Suppose you want a program to display a message that asks the user to change 
disks in one of the drives. To do this you might use the following command: 


Pause Please put a new disk into drive A 


If echo is on, this line will precede the "Strike a key" message when you run 
the batch file. 
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Rem [I] 


Purpose: 


During execution of a batch file, rem displays remarks that are on the same line 
as the rem command in that batch file. 


Syntax: 


rem [comment] 


Comments: 


The comment parameter is a line of text that helps you identify and remember 
what your batch file does. 


The only separators allowed in the comment are spaces, tabs, and commas. 


In your batch file, you can use rem without a comment to add spacing for 
readability. 


Note If echo is off, the rem comment is not displayed. 


Examples: 


The following example shows a batch file that uses remarks for both 
explanation and spacing: 


rem This file formats and checks new disks 
rem It is named checknew.bat 

rem 

pause Insert new disk in drive B 

format B: /v 

chdksk B: 
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Shift [I] 
Purpose: 


Lets you change the position of replaceable parameters in batch file processing. 


Syntax: 


shift 


Comments: 


You can use the shift command to change the positions of (replaceable) 
command line parameters. 


Usually, command files are limited to handling ten parameters, %0 through %9. 
But by using the shift command, you can access more than ten parameters. 
This means that if there are more than ten parameters given on a command line, 
those that appear after the tenth (%9) will be shifted one at a time into %9. 


You can use the shift command even if you have less than ten parameters. 


Warning There is no backward shift command. Once you have executed 
shift, you cannot recover the first parameter (%0) that existed before the shift. 


Examples: 


The following file, called mycopy.bat, shows how to use the shift command 
with any number of parameters. It copies a list of files to a specific directory. 


rem mycopy.bat copies 
rem any number of files 
rem to a directory. 
rem The command is 
rem mycopy dir files 
set todir = $1 

zone 

shift 

if "%$1"=="""goto two 
copy %1 %todir% 

goto one 

:two 

set todir= 

echo All done 


5 MS-DOS Editing 
and Function Keys 


In this chapter, you will learn about 


e The MS-DOS editing and function keys 
e The editing template 
e The MS-DOS control characters 


Special MS-DOS Editing Keys 


Many operating systems handle command input differently than MS-DOS does. 
One difference in particular that sets MS-DOS apart is its set of special editing 
keys. For instance, with MS-DOS you don’t have to type the same sequences of 
keys repeatedly, because the most recently typed command line is 
automatically placed in a special storage area called a template. 


By using the template and the special editing keys, you can take advantage of 
the following MS-DOS features: 


e You can repeat a command instantly by pressing two keys. 
e Ifyou make a mistake in a command line, you can edit and retry it without 
having to retype the entire line. 


e = With a minimum of typing, you can edit and execute a command line that 
is similar to a previous one. 


How MS-DOS Uses the Template 


When you type a command and press the RETURN key, MS-DOS automatically 
sends it to the command processor (command.com) for execution. At the same 
time, MS-DOS also saves a copy of this command in the template. You can 
then recall or modify the command by using the MS-DOS special editing keys. 
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The following figure shows how the template relates to the command line: 


command line 







































































The MS-DOS Editing Keys 


The MS-DOS editing keys provide you with a set of editing tools that can save 
you time. You can use them to correct typing mistakes, repeat frequently used 
commands, or create similar command lines. These keys are described briefly 
in the following table and more fully later in Chapter 6, "The Line Editor 
(Edlin)." 


Key Editing function 

Fl Copies one character from the template to the command line. 

F2 Copies characters up to the character specified in the template 
and puts these characters on the command line. 

F3 Copies all remaining characters in the template to the command 
line. 

DEL Skips over (does not copy) a character in the template. 

F4 Skips over (does not copy) the characters in the template up to 


the character specified. 
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ESC Voids the current input and leaves the template unchanged. 

INS Enters/exits insert mode. 

F5 Makes the new line the new template. 

F6 Puts a contRoL-z (1AH) end-of-file character in the new 
template. 


Yov’ll use these special editing keys in conjunction with the template, which 
you'll leam to use in the next section. 
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How to Use the MS-DOS Template 


Examples: 


Suppose you want to see the directory information for a file named invest.mnt. 
To get this information you could type the following command: 


dir invest.mnt 

This command line (dir invest.mnt) is also saved in the template. If you want to 
repeat the command, just press two keys: F3 and RETURN. 

MS-DOS displays the repeated command on the screen when you press F3, as 
shown below: 


dir invest.mnt 


Notice that when you press the F3 key, MS-DOS copies the contents of the 
template to the command line; pressing the RETURN key then sends the command 
line to the command processor for execution. 


If you want to display information about a file named invest.rpt, you can use 
the contents of the template. Pressing F2, followed by the letter m, copies all 
characters from the template to the command line, up to but not including the 
m. MS-DOS displays 


dir invest. _ 


Note that the underline is your cursor. Now type the letters rpt to get the 
following result: 


dir invest.rpt_ 


The command line (dir invest.rpt) is now in the template and ready to be sent to 
the command processor for execution. To run the command, press the RETURN 
key. 
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Now, assume that you want to run the following command: 

type invest.rpt 

To do this, type the word type and then press the following sequence of keys: 
INS, SPACEBAR, F3, RETURN. 


Notice as you type that the characters appear on the command line, overwriting 
their corresonding characters in the template. Before you press the ws key, the 
word type replaces the word dir (and the space following it) in the template. 
After you press the ws key, this automatic replacement feature is turned off. 


To insert a space between the word type and the filename invest.rpt, you 
pressed ms and then the spacesar. Finally, to copy the rest of the template to the 
command line, you pressed F3 and then the RETURN key. 


The command line type invest.rpt has been processed by MS-DOS, and the 
template now looks like this: 


type invest.rpt. 


If you had misspelled type as pyte, for example, a command error would have 
occurred. Still, instead of throwing away the whole command, you could save 
the misspelled line before pressing the RETURN key. You can do this by pressing 
the Fs key before the RETuRN key, creating a new template: 


pyte invest.rpt 
Then you can use the peL and ws keys to get the same result, as follows: 


DEL DEL F1 INS yp F3 
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To illustrate how the keys you type affect the command line, compare the key 
pressed with its result (shown beneath it along with a description of the effect). 


DEL 
= Skips over 1st template character 
DEL 

z Skips over 2nd template character 
Fl 

ta Copies 3rd template character 

INS yp 

typ_ Inserts two characters, y and p 

F3 

type invest.rpt_ Copies rest of template 


Notice that pet does not affect the command line. Instead, it affects the 
template by deleting the first character. Similarly, pressing the f4 key deletes 
characters in the template, up to, but not including, a given character. 


These special editing keys do give you more power and flexibility when you 
are typing. But in addition to these keys, MS-DOS also has control characters 
that help you control the output from a command, or contro] the contents of the 
current command line. The next section describes how to use the MS-DOS 
control characters. 


The MS-DOS Control Characters 


A control character affects the command line in a special way. For example, 
you use CONTROL-c to stop running the current command, and you use CONTROL-S 
to suspend the screen output from a command. 


Note When you type a control sequence, such as CONTROL-c, you must hold 
down the contro key and then press the c key. 
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The following table shows the MS-DOS control characters and describes what 
they do: 


Control 

character What it does 

CONTROL-C Aborts the current command. 

CONTROL-H Removes the last character from a command line, and 
erases that character from the terminal screen. 

CONTROL-J Inserts a physical end-of-line, but does not empty the 
command line. Use the LineFEED key to extend the current 
logical] line beyond the physical limits of the terminal 
screen, 

CONTROL-N Causes echoing of output to a lineprinter. 

CONTROL-P Causes terminal output to a lineprinter. 

CONTROL-S Suspends output display on the screen. Press conrROL-s 
again to resume. 

CONTROL-X Cancels the current line, empties the command line, and 


then outputs a backslash (\), RETURN, and LINEFEED. CONTROL-X 
does not affect the template used by the special editing 
commands. 


Now that you have been introduced to the special editing and function keys of 
MS-DOS, in the next chapter yov’ll learn how to use them with Edlin, the MS- 
DOS line editor. 


6 The Line Editor (Edlin) 


Edlin is the MS-DOS line editor that you can use to create text files and save 
them on your disks. Edlin also helps you to update existing files by deleting, 
changing, and inserting lines in files. And even though it isn’t a word 
processor, Edlin does make it easy for you to create and revise files such as 
memos, letters, reports, or GW-BASIC programs. 


In this chapter, you will learn 


How to start Edlin 

How to end Edlin and save edits 

How to use the MS-DOS special editing keys with Edlin 
How to use Edlin commands 
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How Edlin Works 


Edlin divides the text from a file into lines, each line containing up to 253 
characters. It gives each line a number and always numbers the lines 
consecutively. But even though you see these line numbers on the screen when 
you use Edlin, they are not part of the file. 


When you insert lines of text in a file, the line numbers after the inserted text 
are automatically adjusted. Similarly, when you delete lines in a file, the line 
numbers following the deleted text are automatically renumbered. 


How to Start Edlin 


To start Edlin, type a command of the following form: 
edlin filename 


where filename is the file you want to edit. If you are creating a new file, 
filename should be the name or pathname of the file you want to create. If 
Edlin does not find this file on the default disk drive, it craetes a new file with 
the name or pathname that you specify. For example, if you want to create a 
file called budget.jun, you would type the following command and then press 
the RETURN key: 


edlin budget. jun 
Once you type the command, Edlin prompt displays the following: 


New file 
x 


Note that the Edlin prompt is an asterisk (*). 
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To begin entering text you must type an i (insert) command to insert lines. The 

i command is discussed later in this chapter. For now you can type lines of text 

into your file, or use any of the Edlin commands, which are also discussed later 
in this chapter. 


Note Be sure to press the RETURN key at the end of each line. 


Suppose you want to edit an existing file called budget.may. To do this you 
would type the following: 


edlin budget.may 


When Edlin finds the budget.may file, it loads it into memory. If your 
computer has enough memory to load the entire file, Edlin displays the 
following message: 


End of input file 
* 


You can then edit the file by using Edlin commands. 


If the file is too large to be loaded into memory, Edlin loads lines from the file 
until memory is 3/4 full, and displays the asterisk (*) prompt. You can then edit 
the portion of the file that is in memory. 


To edit the rest of the file, you must save some of the edited lines on a disk to 
free memory. Edlin will then be able to load the remaining unedited lines from 
a disk into memory. For more information on editing large files, see the w 
(write) and a (append) commands later in this chapter. 


How to End Edlin and Save Your Changes 


When you finish your editing session and the cursor is at the asterisk (*) 
prompt, you can save your original file and the updated (new) file by using the 
e (end) command, discussed later in this chapter. Edlin renames your original 
file with the extension .bak, and saves the updated file with the filename and 
extension you gave when you started Edlin. 


Warnings 


e You cannot update a file with an extension of .bak because when you try 
to save your file, Edlin always saves the original file as .bak, overwriting 
any existing .bak file. Thus, any changes you made to the existing .bak file 
using Edlin are lost. If you need to update a .bak file, rename it with 
another extension (using the MS-DOS ren command discussed in Chapter 
3, "MS-DOS Commands"), and start Edlin by using the new filename. 
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e Ifa .bak file already exists and has read-only permission, the updated file 
will be saved by using the e (end) command, but the original file will not 
be saved in a .bak file. Edlin detects this condition when you first start to 
edit a file and displays the following message: 


WARNING! Backup file is read-only -- backup 
will not be made 


Special Editing Keys 
To edit your text files, you can also use the special editing keys and template 


introduced in Chapter 5, "MS-DOS Editing and Function Keys." 


The following table summarizes the commands, codes, and functions of the 
special editing keys. Descriptions of these special editing keys follow the table. 


Key Purpose 

FI Copies one character from the template to the new line. 

F2 Copies all characters from the template to the new line, up to the 
character specified. 

F3 Copies all remaining characters in the template to the screen. 

DEL Does not copy (skips over) a character. 

F4 Does not copy (skips over) the characters in the template, up to 
the character specified. 

ESC Clears the current input and leaves the template unchanged. 

INS Enters/exits insert mode. 

F5 Makes the new line the new template. 

BKSP Deletes a character from the command line and places the cursor 


back one character in the template. 


The following pages describe how to use each of the MS-DOS editing keys 
with Edlin. 
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The F1 Key 


When you press the rı key, Edlin copies one character from the template to the 
current line, and turns insert mode off. As an example of how to use the Fl key 
with Edlin, type the following lines: 


1:*Sharpe Office Supplies. 
2:* 


At the beginning of the editing session, the cursor (shown by the underline) is 
at the beginning of the line. When you press the Fi key, Edlin copies the first 
character, S, to line 2 as shown here: 


2:*s_ 
Each time you press the Fi key, one more character appears: 


Fl 
2:*Sh_ 

Fl 
2:*Sha_ 
F1 
2:*Shar_ 


The F2 Key 


When you press the r2 key, Edlin copies all the characters, up to a given 
character, from the template to the current line. The given character is the one 
that you type immediately after pressing F2. Edlin does not copy or display the 
given character on the screen, but it does copy and display the characters from 
the template up to the position of that character. Of course, if the template does 
not contain the character, Edlin does not copy anything. 


If you use the m key, you automatically tum off insert mode. 


As an example of how to use the F2 key with Edlin, if you type Sharpe Office 
Supplies. on line 1 and then press F2, followed by the letter c, Edlin copies the 
characters up to the c in the word Office. 


F2 C 
2:*Sharpe Offi_ 
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The F3 Key 


When you press the m key, Edlin copies the remaining characters in the 
template to the current line. No matter where the cursor is when you press the 
F3 key, Edlin displays the rest of the line and leaves the cursor at the end of the 
line. As an example of how to use the F3 key with Edlin, if you type Sharpe 
Office Supplies. on line 1 and press F3, Edlin copies the characters in the 
template (from line 1) to the line with the cursor (shown in line 2): 


F3 
2:*Sharpe Office Supplies. _ 


Also, this command automatically turns off insert mode. 


The DEL (Delete) Key 


Each time you press the peL key, Edlin skips over and does not copy the next 
character in the template. The action of the peL key is similar to that of the Fi 
key, except that peL skips a character in the template instead of copying it to the 
current line. Thus, if the template already contains "Sharpe Office Supplies.” 
and you press the peL key, Edlin skips over the first character, S. The cursor 
does not move as Edlin changes the template. So to see how much of the line 
has been skipped over, press the F3 key. This action moves the cursor past the 
last character of the line: 


DEL 
F3 
2:*harpe Office Supplies. _ 


The F4 Key 


When you press the r4 key, Edlin skips over all characters up to a given 
character in the template. Edlin does not copy or display any of the characters 
up to and including the given character. Of course, if the template does not 
contain that character, Edlin does not skip any characters. 
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Note that the action of the f4 key is similar to that of the F2 key, except Fa skips 
over characters in the template instead of copying them to the current line. 
Using the same template example, "Sharpe Office Supplies.” the F4 key 
followed by the letter c, causes Edlin to skip over all the characters in the 
template up to the c in the word Office. The cursor does not move as Edlin 
changes the template. To see how much of the line has been skipped over, press 
the F3 key to copy the template. This action displays the rest of the line and 
moves the cursor to the end of the line: 


F4 c 
F3 
2:*ce Supplies._ 


The ESC (Escape) Key 


When you press the gsc key, Edlin clears the current line and leaves the 
template unchanged. gsc also prints a backslash (\), RETURN , and LINEFEED, and 
turns insert mode off. The cursor is at the beginning of the line. If you then 
press the F3 key, Edlin copies the template to the current line, making it appear 
as it was before you pressed the Esc key. For example, type the following lines: 


1: Sharpe Office Supplies. 

2:*The World Leader _ 

To cancel the current line, line 2, press Esc. Notice that a backslash appears on 
line 2 to tell you it has been canceled: 

ESC 

2:*The World Leader\ 

Press the RETURN key to keep line 1, or to perform any other editing functions. 
Now if you press F3, Edlin copies the original template to the line: 


F3 
2: Sharpe Office Supplies. 
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The INS Key 


The ws key toggles between insert mode and replace mode. When you start 
Edlin, you are automatically in replace mode. The first time you press the ms 
key, Edlin enters insert mode. In insert mode the cursor in the template does 
not move, but in the current line it moves as you insert each character. When 
you finish inserting characters and press the ws key again, Edlin re-enters 
replace mode with the cursor at the same character in the template as when you 
entered insert mode. 


The F5 Key 


When you press the Fs key, Edlin copies the current line to the template and 

deletes the previous contents of the template. Pressing Fs also displays an @ 

("at" symbol), and outputs a RETURN and a LINEFEED. When you press Fs, Edlin 
empties the current line and turns off insert mode. 


Note rs performs the same function as the Esc key, but it changes the template, 
printing an @ instead of a backslash. 


As an example of how to use the Fs key with Edlin, type the following line: 


1:*Sharpe Office Supplies. 
2:* 


Remember that at the beginning of the editing session, the cursor (shown by the 
underline) is at the beginning of the line. Now type the following sequence of 
keys and words (the results are shown below each key sequence): 


F2 C 
2:*Sharpe Offi_ 


INS cial 
2:*Sharpe Official _ 


INS Sharpeware. 
2:*Sharpe Official Sharpeware. _ 
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At this point, suppose you want to add a word at the beginning of this line, but 
you don’t want to backspace and retype the whole line. Just press the Fs key to 
put the current line into the template. 

1: Sharpe Office Supplies. 

2:*Sharpe Official Sharpeware.@ 

The @ shows that this new line is now the new template. To add the word 
Introducing :, followed by a space, at the beginning of the line, press ins and 
type the following sequence of keys and words (the results are shown below 
each key sequence): 

Ns Introducing 

2:*Introducing: _ 

Then press the F3 key to insert the contents of the template. 


F3 
2:*Introducing: Sharpe Official Sharpeware. _ 


The BKSP (Backspace) Key 


This key deletes a character from the command line and places the cursor back 
one character in the template. 


Note You can also press the Lerr direction key or CONTROL-H to backspace. For 
example, suppose that you type the following: 
1:*Sharpe Office Supplier_ 


Then you realize that you meant to type Supplies instead of Supplier. To correct 
this error, you would press the aksp key followed by the letter s. 


BKSP S 
1:*Sharpe Office Supplies __ 
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Using Edlin Commands 


Edlin includes several commands that help you to edit lines of your file. The 
following table summarizes these commands: 


Letter 
a 


= 


fe ae oe, bee 


Purpose 

Appends lines from disk to memory. 

Copies lines. 

Deletes line. 

Edits a line or lines. 

Ends editing session and saves edits. 

Inserts lines of text. 

Lists a range of lines. 

Moves a range of text to a specified line. 

Pages through a file 23 lines at a a time. 

Quits the editing session without saving the file. 
Replaces text. 

Searches for text. 

Transfers the contents of another file into the file being edited. 
Writes specified lines from memory to disk. 


Some Tips for Using Edlin Commands 


Once you have started editing a file with Edlin, you can use the Edlin 
commands to edit lines of text in the file. Here are a few things to remember 
when using Edlin commands: 


e You can use pathnames in commands. For example, by typing the 
following command, you can edit a file named report.may in a 
subdirectory named \ sharpe\ budget: 


edlin\sharpe\budget \report.may 


e You can refer to lines with numbers relative to the current line (identified 
with an asterisk, *). To indicate lines before the current line, use a minus 
sign with a number; to indicate lines after the current line, use a plus sign 
with a number. For example, to list 10 lines before the current line, the 
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current line, and 10 lines after the current line, you could type this 
command: 


-10,+10L 


Note A capital L is used here for the L (list) command to avoid 
confusion with the number one. A small letter | would work just as well. 


Edlin ignores spaces between the line number and command. For the 
examples in this chapter, spaces are omitted. 


Generally, Edlin allows you to type one command after another on the 
same command line. However, if you want to use the Edlin dine (edit) 
command to edit a specific line, you must separate the line number from 
the other commands with a semicolon. For example, the following 
command edits line 15, then displays lines 10 through 20 on the screen: 


15;-5,+5L 


When using control key sequences, simply press and hold the conrrot key 
followed by the control] character (such as z or c or v). For example, if you 
want to search for a phrase that includes the control character CONTROL-Z, 
you could use a command like this one: 


smonthly budget CONTROL-Z-5,+5L 


Note that you do not type the letters CONTROL but instead press the 
CONTROL key as you press the z key. 


You can insert a control character, such as CONTROL-c, into text by using 
the quotation mark character, contro.-v, before it while in insert mode. 
CONTROL-V tells MS-DOS to recognize the next capital letter typed as a 
control character. For example, the following command finds the first 
occurrence of conTROL-z (the end-of-file mark) in a file: 


sCONTROL-VZ 

To insert CONTROL-V into the text, press CONTROL-v and type V. 

The controu-z character is usually an end-of-file identifier for Edlin. If 
you have conTroL-z characters elsewhere in your file, you must tell Edlin 
that these other control characters do not mean end-of-file. To tell Edlin 


to ignore the CONTROL-z characters in the file and to show you the entire 
file, use the /b switch when you start Edlin. For example, the following 
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command lets you start editing the file macro.asm and ignores any 
CONTROL-z characters: 


edlin macro.asm /b 


Edlin Command Options 


Many Edlin commands accept one or more options. The effect of a command 
option varies, depending on which command you use it with. The following list 
describes each option. 


The Line Option 


The line option is a line number that you type. Use a comma or space to 
separate the numbers from other line numbers, other options, and from the 
command. 


You can specify line in one of three ways: 


Tupe How it works 


linenumber You may use any number less than 65,534. If you specify a 
number larger than the largest existing line number, then 
line refers to the line after the last line number. 


period (.) If you specify a period for line, it refers to the current line 
number. The current line is the last line you edited, not 
necessarily the line you last displayed. Edlin marks the 
current line with an asterisk (*) between the line number 
and the first character. 


pound sign (#) The pound sign indicates the line after the last line number 
in the file. If you type # for line, it is the same as typing the 
last line number plus one. 


RETURN key If you type a command and then press the RETURN key 
without any of the line markers in this list, Edlin uses a 
default value for each command (default values may be 
different for each command). 
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The Question Mark Option 


The question mark (7?) option tells Edlin to ask you if the correct string has 
been found. You use the question mark only with the r (replace) and s (search) 
commands. Before continuing, Edlin waits for you to type a Y or press the 
RETURN key for a "Yes" response, or to press any other key for a "No" response. 


The Text Option 


The text option specifies text to be found, to be replaced, or to replace other 
text. Use the fext option only with the s (search) and r (replace) commands. 


The Edlin Commands 


The remaining pages in this chapter describe the Edlin commands. Each 
description includes the correct usage (syntax) of a command. Also, each 
command description includes several comments and examples that offer 
advice, help, and even some shortcuts for using Edlin. 
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Edlin’s Append Command: a 
Syntax: 

[n]a 

Comments: 


If you are editing a large file that is too large to read into memory all at once, 
you can use the a (append) command. This command lets you read in portions 
of your file to memory as you need to work on them. The n parameter is the 
number of lines that you want to read into memory. 


When you start Edlin, it reads as many lines as possible into memory. If the 
size of your file exceeds available memory, you must edit your file in stages. 
That is, after you have edited the first part of a large file, you must write lines 
that you have already edited onto your disk. Then you can load unedited lines 
from your disk into memory by using the a (append) command. 


Notes: 


If you do not specify the number of lines to append, Edlin adds lines to the 
available memory until it is 3/4 full, but does nothing if available memory is 
already 3/4 full. If available memory is already full, you may be able to free 
memory by quitting other applications that may be running or by restarting MS- 
DOS. Restarting MS-DOS clears memory being used by programs that remain 
resident in memory, even after they finish running. 


After the a (append) command reads the last line of the file into memory, Edlin 
displays the message "End of input file." 


Example: 


Suppose you have a file so large that the last 100 lines would not fit into 
memory. After editing the first part of the file, and writing a portion back to the 
disk, you could use this command to read the remaining 100 lines into memory: 


100a 


For information about how to write edited lines to your disk, see the w (write) 
command in this chapter. 
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Edlin’s Copy Command: c 
Syntax: 


[line], [line],line[ ,count]c 


Comments: 


The c (copy) command copies a range of lines to a specified line number, and 
when used with the count option, copies this range as many times as you want. 
The first and second line options specify the range of lines that you want to 
copy. If you omit the first or second line option, Edlin defaults to the current 
line. The third line option specifies the line before which Edlin will place the 
copied lines. 

You must not overlap the line numbers or you will get an "Entry error" 
message. For example, this command would result in an error message: 


3,20,15c 


If you do not specify a number for the count option, Edlin copies the lines one 
time and automatically renumbers the file after the copy. 


Example: 
If you type 
1,5,6c 


Edlin copies lines 1 through 5 and duplicates them one time, beginning on line 
6. Thus lines 1 through 5 and 6 through 10 are identical. 
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Edlin’s Delete Command: d 


Syntax: 


[line]f,line]d 


Comments: 


The d (delete) command deletes a specified range of lines in a file. If you omit 
the first line option, Edlin defaults to the current line (the line with the asterisk 
next to the line number). If you omit the second line option, Edlin deletes just 
the first line. Remember, too, that when you delete lines, Edlin automatically 
renumbers the file. 


Example: 


If you type the following command, Edlin deletes line 7 then renumbers line 8 
and all following lines: 

Td 

If you want to delete a block of text on lines 22 through 32, you can type 


22, 32d 


The d command removes lines 22 through 32, inclusively, from your file. 


Finally, suppose that you want to delete a range of lines beginning with the 
current line, line 7, through line 11. Type the following: 


,lld 
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Edlin’s Line Edit Command 


Syntax: 


[line] 


Comments: 


The line option allows you to specify the line number of text you want to edit. 
When you type a line number as a command, Edlin displays the line number 
and the text on that line; then, on the line below, Edlin reprints the line number. 
Now you can retype the line, or use the Edlin editing keys to edit it. The 
existing text of the line serves as the template until you press the RETURN key. 


If you press the RETURN key without typing a line number, Edlin edits the line 
after the current line. 


When you have edited the line, simply press the RETURN key to accept the line. 


Warning If you press the reTURN key while the cursor is in the middle of a 
line, Edlin deletes the remainder of the line. 


Example: 

Suppose that the following file exists and is ready to edit: 
Dear Mr. Dimm, 

I was sorry to hear of your recent 
hospitalization due to electrical 


shock from our Automatic 
: Pencil Sharpener. 


Ob WN FE 


a 


In line 5, say you want to insert the product’s name, X-1000. To edit line 5, 
type the number 5. Edlin then displays the contents of the line with the cursor 
below the line: 


5:*shock from our Automatic 
5:%* 


6.18 MS-DOS User's Reference 


Now you simply use the F2 key to skip to the A in the word Automatic, and type 
F2 A INS X-1000 

5:*shock from our X-1000 
F3 RETURN 

5:*shock from our X-1000 Automatic 


At the Edlin prompt, type L to see the file: 


: Dear Mr. Dimm, 


I was sorry to hear of your recent 
hospitalization due to electrical 
:*shock from our X-1000 Automatic 
Pencil Sharpener. 


HOSP WD 
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Edlin’s End/Save Command: e 
Syntax: 


e 


Comments: 


The e (end) command saves the edited file on your disk, renames the original 
input file filename.bak, and then exits Edlin. If you created the file during this 
editing session, Edlin does not create a backup (.bak) file. 

The e (end) command takes no options. This means that you must select the 
directory and drive that you want to save the file on when you start Edlin. If 
you don’t select a drive when you start Edlin, it saves the file on the disk in the 
default drive. However, you can still copy the file to a different drive by using 
the MS-DOS copy command. 


Before using the e command to save your file, make sure that the disk contains 
enough free space for the entire file. If it doesn’t, Edlin may not be able to 
write the entire file to the disk. The edited file will be lost, although Edlin may 
have saved part of the file on the disk. 


Notes: 


If a .bak file already exists and is a read-only file, the updated file is saved by 
using the e (end) command. However, the original file does not detect this 
condition when you first start to edit a file, so MS-DOS displays this message: 


Warning: Backup file is read only -backup will not be 
made. 


Example: 


To end an Edlin session and save the edits you have made, simply type 
e 


Edlin saves your edited file and returns you to the MS-DOS prompt (for 
example, A>). 
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Edlin’s Insert Command: i 
Syntax: 

[line]i 

Comments: 


The i (insert) command allows you to insert text immediately before the 
specified line. If you are creating a new file, you must type the i (insert) 
command before you can insert a new line of text. Text begins on line 1, and 
the next line number appears automatically each time you press the RETURN key. 


Edlin remains in insert mode until you press contTRoL-c. When you finish the 
insertion and exit insert mode, the line immediately following the inserted lines 
becomes the current line. Edlin automatically increments the line numbers that 
follow the inserted section by the number of lines that you inserted. 


If you do not specify line, the default is the current line number and Edlin 
inserts the lines before the current line. If line is a number larger than the last 
line number, or if you specify a pound sign (#) as line, Edlin appends the 
inserted lines to the end of the file. In this case, the last line that you inserted 
becomes the current line. 


Example: 


Suppose the following file exists and is ready to edit: 


[a 
ae 


Dear Mr. Dimm, 


I was sorry to hear of your recent 
hospitalization due to electrical 
shock from our X-1000 Automatic 
Pencil Sharpener. 


Sincerely, 


OV OAD UW SW ND 


m. 


I.R. Sharpe, President 
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This letter doesn’t really offer any compensation for the accident, so you might 
want to add a comforting thought to the letter to console Mr. Dimm. To insert 
text before line 8, type 8i. The result is 


8:* 

Now type the following lines, which will begin on line 8: 

8:*As a result of your accident, we 

Press the RETURN key at the end of each line, and continue typing the next line: 


9:*are redesigning our manual to 
10:*warn our customers against trying 
11:*to sharpen metal objects. 


To end the insertion, press conTROL-c on the next line. To insert a blank line 
immediately before the current line (line 12), type i. The result is 


12:*_ 


Insert a blank line by pressing RETURN, and end the insertion by pressing 
CONTROL-c on the next line. Then, to list the file and see the result, type L. The 
result is 


Dear Mr. Dimm, 


1 

2 

3: I was sorry to hear of your recent 
4: hospitalization due to electrical 
5: shock from our X-1000 Automatic 

6: Pencil Sharpener. 

7 
8 


: As a result of your accident, we 
9: are redesigning our manual to 
10: warn our customers against trying 
11: to sharpen metal objects. 
12: 
13:*Sincerely, 
14: 
15: I.R. Sharpe, President 
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Edlin’s List Command: L 


Syntax: 


[line](,line]L 


Comments: 


The L (list) command displays a range of lines, including the two lines 
specified. If you only specify one of the line options, Edlin uses default values. 
For example, if you omit the first line option, as in the following example, 
Edlin displays 23 lines, beginning 11 lines before the current line and ending 
with the specified line: 


line L 


The beginning comma shows that you omitted the first line option. If you omit 
the second line option, Edlin displays 23 lines, starting with the specified line. 
If you type L with no line option at all, Edlin displays 23 lines—beginning 
with the 11 lines before the current line. 


Notes: 


e Ifthe specified line is more than 11 lines before the current line, the 
display will be the same as if you omitted both options. 


e A capital letter "L" has been used here to avoid confusion with the number 
"1" (one). A small letter "1" would work just as well. 


Example: 


To list lines 5 through 10, inclusive, type 
5,10L 
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Edlin’s Move Command: m 
Syntax: 

[line,][+]line,Jinem 

Comments: 


The m (move) command lets you transfer a block of text to another location in 
a file. The first and second line options specify the range of lines that you want 
to move. The third line option specifies the line to which you want to move the 
first line in the range. 

Edlin automatically renumbers the lines after it moves them. For example, the 


following command moves the text from the current line—plus 25 lines—to 
line 100: 


,+25,100m 


If the line numbers that you specify overlap, Edlin displays an "Entry error" 
message. 


Example: 


Suppose the following file exists and is ready to edit. 


Dear Mr. Dimm, 


1 
2 
3: I was sorry to hear of your recent 
4: hospitalization due to electrical 
5: shock from our X-1000 Automatic 

6: Pencil Sharpener. 

7 

8 


As a result of your accident, we 
9: are redesigning our manual to 
10: warn our customers against trying 
11: to sharpen metal objects. 


13: Sincerely, 


15: I.R. Sharpe, President 
16: Sharpe Office Supplies 
17: The World Leader in Office Sharpeware 
18: Our motto: "You oughta be Sharpe too" 
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What if you prefer to have the motto at the start of the letter? If so, you could 
move lines 16-18 to line 1, by typing the following command: 


16,18,1m 


The result of this command is 


DBA nODBWN PE 


Sharpe Office Supplies 

The World Leader in Office Sharpeware 
Our motto: "You oughta be Sharpe too" 
Dear Mr. Dimm, 


I was sorry to hear of your recent 
hospitalization due to electrical 
shock from our X-1000 Automatic 
Pencil Sharpener. 


As a result of your accident, we 
are redesigning our manual to 
warn our customers against trying 
to sharpen metal objects. 


Sincerely, 


I.R. Sharpe, President 
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Edlin’s Paging Command: p 
Syntax: 


[line][,line]p 


Comments: 


The p (page) command displays a file one screen (23 lines) at a time. The first 
line option specifies the line at which Edlin starts displaying. The second line 
option specifies how many lines appear on each page. If you do not type the 
first line, Edlin starts the page at the line after the current line. If you do not 
type the second line option, Edlin lists 23 lines on each page. 


Example: 


To view lines 100 through 200 and to see the text one screen at a time, you 
could type this command: 


100,200p 
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Edlin’s Quit/No Save Command: q 
Syntax: 


q 


Comments: 


The q (quit) command is useful if you don’t want to make any changes to a file. 
This command exits to the MS-DOS operating system and does not save any 
editing changes. If you use the q (quit) command, Edlin prompts you to make 
sure you don’t want to save the changes. If you want to save changes as you 
exit Edlin, use the e (end) command. 


Notes: 


When you exit Edlin, it erases any previous copy of the file that has a .bak 
extension. But if you quit Edlin (q) and reply Y (for Yes) to the "Abort edit 
(Y/N)?" message, Edlin will not delete your previous backup copy. 


Example: 


The following example shows how to quit Edlin without saving your changes. 
1. Press conrroL-c to leave insert mode. 

2. At the asterisk (*) prompt, type q. 

3. The message "Abort edit (Y/N)?" appears. 

4. Type Y (for Yes) to abort the edit, then press the RETURN key. 
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Edlin’s Replace Command: r 
Syntax: 


[line][,line][? ]rtext] CONTROL-Z text2 


Comments: 


The r (replace) command replaces all occurrences of a string of text in a range 
with a different string of text. The Jine options show the range that r (replace) 
uses. Each time Edlin finds text], it replaces it with text2. Then Edlin displays 
each line that changes. 


For example, the following command would change the word "mine" each time 
it occurred in a 20-line file to the word ours: 


1, 20rmineconTROL-zours 


Note that you press the controL and z keys at the same time. Do not type 
"CONTROL-Z." 


If a line contains two or more replacements, it is displayed once for each 
change. If you include a question mark (?) in your command, Edlin asks 
"O.K.?." If you press Y (for Yes) or RETURN, text2 replaces text], and Edlin 
looks for the next occurrence of text]. If you press any other key in response, 
Edlin does not make the change for that occurrence of text]. When Edlin has 
made all the changes, the asterisk prompt reappears. 


When you do not specify text/, the r command assumes the old (any previous) 
value. If this is the first replacement that you have done during this editing 
session, and if you do not specify text], the command ends. If you do not 
specify text2, you must end text] by pressing the RETURN key. 


If you omit the first line option, Edlin uses the line after the current line, by 
default. The default for the second line option is the line following last line of 
the file (represented by the symbol "#"). 

If you end text] with a contRoL-z and do not specify text2, Edlin assumes you 
want blank spaces for text2. For example, suppose you want to delete all 
occurrences of the word "clients" from your file. To do this you could simply 
type the following command, then press ConTROL-z and RETURN: 


relients 
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The next command replaces clients with the previous text2: 

relients 

The following command makes the previous text] become the previous text2: 
r 


Note that previous refers to an earlier string of text specified in an s or r 
command. 


Example: 


Suppose the following file exists and is ready for editing: 


1: Dear Mr. Dimm, 


2 
3: I was sorry to hear of your recent 
4: hospitalization due to electrical 
5: shock from our X-1000 Automatic 

6: Pencil Sharpener. 

7 

8 

9 


As a result of your accident, we 
are redesigning our manual to 
10: warn our customers against trying 
11: to sharpen metal objects. 


13: Sincerely, 
14: 
15: I.R. Sharpe, President 


Now suppose that in lines 5 through 10 you want to replace all occurrences of 
the word our with the word the. To do this you would simply type 5,10 rour; 
press CONTROL-Z, type the, and press the RETURN key. The result is 


5: shock from the X-1000 Automatic 
8: As a result of ythe accident, 
9: are redesigning the manual to 
10: warn the customers against 


In the previous example, two unwanted changes occurred in lines 8 and 10. To 
avoid the changes and to confirm each replacement, you can use the same file 
with a slightly different command. 
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In the next example, you will see how to replace only certain occurrences of 
our with the. At the Edlin prompt, type the following sequence of keys and 
words, and then press the RETURN key: 


1,15? rour CONTROL-Z the 
The result is 


5: shock from the X-1000 Automatic O.K.? y 
8: As a result of *ythe accident, we 


O.K.? n 

9: are redesigning the manual to 
O.K.? y 
10: warn the customers against trying 
O.K.? n 


* 


Type the list command, L, to see the result of all these changes: 


5: shock from the X-1000 Automatic 


8: As a result of your accident, we 
9: are redesigning the manual to 
10: warn our customers against trying 
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Edlin’s Search Command: s 
Syntax: 


[line] ,Jine][? |stext 


Comments: 


The s (search) command searches a range of lines for a string of text. The first 
and second line options specify the range of lines for Edlin to search. You end 
the text option by pressing the rETuRN key. Edlin displays the first line that 
matches the string; that line then becomes the current line. Unless you type the 
question mark (7?) option, the s (search) command ends when it finds the first 
match. If Edlin cannot find a line with a match, it displays the message "Not 
found.” 


If you include the question mark option (?), Edlin displays the first line with 
matching text and prompts you with the message "O.K.?". If you press either Y 
(for Yes) or the RETURN key, this line becomes the current line and the search 
ends. If you press any other key, the search continues until another match is 
found, or until all lines have been searched. (The search ends when Edlin 
displays the "Not found" message.) 


If you do not type the first line number, Edlin defaults to the line after the 
current line; and if you do not type the second line number, it defaults to # (the 
line after the last line of the file). 


If you omit the text option, Edlin uses the text from any previous s or r 
(replace) command. If this is the first s or r command you have used this 
session, and you have not specified a search string, the s command ends 
immediately. 
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Example: 


Suppose the following file exists and is ready for editing: 


Dear Mr. Dimm, 


1 
2 
3: I was sorry to hear of your recent 
4: hospitalization due to electrical 
5: shock from our X-1000 Automatic 

6: Pencil Sharpener. 

7 

8 


As a result of your accident, we 
9: are redesigning our manual to 
10: warn our customers against trying 
11: to sharpen metal objects. 


13: Sincerely, 
14: 
15: I.R. Sharpe, President 


To search for the first occurrence of the word to, type the command 2,12 sto 
and press the RETuRN key. Edlin displays the following lines: 


3: I was sorry to hear of your recent 


To search through several occurrences of a string until the correct string is 
found, type the command 1, ? sto. The result is 


3: I was sorry to hear of your recent 
O.K.? 


If you press any key (except Y or the rETuRN key), the search continues, so type 
N (for No) here: 


O.K.?n 
Continue: 


4: hospitalization due to electrical 
O.K.? 


Now press Y to terminate the search: 


O.K.? y 
* 
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Edlin’s Transfer Command: t 
Syntax: 


[line]tfilename 


Comments: 


The t (transfer) command puts the contents of one file into another file, or into 
the text you are typing. Edlin inserts the filename at the line number you give 

in the line option, and then automatically renumbers the lines. If you omit the 

line number, Edlin inserts the text on the current line. 


Example: 


To copy a file named irsharpe.mem to line 12 of the file you are editing, use the 
following command: 


12 t irsharpe.mem 
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Edlin’s Write Command: w 
Syntax: 


[n]w 


Comments: 


The w (write) command writes a specified number of lines to disk. The n 
option specifies the number of lines that you want to write to the disk. You 
need this command only if the file you are editing is too large to fit into 
memory. When you start Edlin, it reads lines from your file until memory is 
3/4 full. 

To edit the remainder of your file, you must write the edited lines in memory to 
your disk. Then you can load additional unedited lines from your disk into 
memory by using the a (append) command, which is described earlier in this 
chapter. 


Example: 


Suppose you had a file so big that the last 100 lines that would not fit into 
memory. After you edited the first part of the file, you could free up enough 
space to edit the last part of the file with this command: 


125w 


Note If you do not specify the number of lines for Edlin to write, it writes 
lines until memory is 3/4 full. But it does not write any lines to your disk until 
memory is more than 3/4 full. Also, Edlin renumbers all of the lines so that the 
first remaining line becomes line number 1. 


7 Link: A Linker 


In this chapter, you'll learn 


e How to create executable files with link 
e How to use link command options 
e How link creates programs 


Note You need to read this chapter only if you are writing programs in a 
computer language that creates object (.obj) files. 


Introduction 


The Microsoft 8086 Object Linker (link) creates executable programs from 
object files generated by the Microsoft Macro Assembler (MASM) or by 
compilers for high-level languages, such as C or Pascal. The linker copies the 
resulting program to an executable (.exe) output file. You can then run the 
program by typing the file’s name on the MS-DOS command line. 


To use link, you must create one or more object files, then submit these files, 
along with any required library files, to the linker for processing. Link 
combines code and data in the object files and searches the named libraries to 
resolve external references to routines and variables. It then copies a relocatable 
execution image and the relocation information to the executable file. Using the 
relocation information, MS-DOS can load the executable image at any 
convenient memory location and then run it. Link can process programs that 
contain up to one megabyte of code and data. 
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Starting and Using Link 


This section explains three methods for starting and using the linker to create 
executable programs. These methods, which you can also mix, let you specify 
link files by 


e Answering prompts 

e Using a command line 

e Using aresponse file 

Once you start link, it will either process the files you supply or prompt you for 


additional files. Also, note that you can stop the linker at any time by pressing 
CONTROL-C. 


Method 1: Using Prompts to Specify Link Files 


When you type the command, link, at the MS-DOS prompt, the linker prompts 
you for the information it needs. Follow these steps: 


1. First, type the following command and press the RETURN key: 
link 


Link prompts you for the object files you wish to link by displaying the 
following message: 


Object Modules [.OBJ]: 


2. Type the name or names of the object files you wish to link. If you do not 
supply extensions for these files, link supplies .obj by default. If you have 
more than one name, make sure you separate each with spaces or plus 
signs (+). If you have more names than can fit on one line, type a plus sign 
(+) as the last character on the line and press the rETuRN key. Link then 
prompts you for additional object files. 


Once you have given all your object filenames, press the RETURN key. The 
linker displays the following prompt: 


Run File [filename. EXE]: 


3. Note that in step 2, filename is the same as the first filename you typed at 
the Object Modules prompt. Type the name of the executable file you 
wish to create, and press the RETURN key. If you do not give an extension, 
link supplies .exe by default. If you want link to supply a default 
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executable filename, just press the RETURN key. The filename will then be 
the same as the first object file, but with the extension .exe. 


Once you have pressed the RETURN key, link displays the following 
prompt: 


List File [NUL.MAP]: 


4. Type the name of the map file you wish to create, then press the RETURN 
key. If you do not supply a filename extension, the linker uses .map by 
default. If you don’t want a map file, don’t type a filename. Just press the 
RETURN key. 


Once you have pressed the RETURN key, link displays the following 
prompt: 


Libraries [.LIB]: 


5. Type the names of any library files containing routines or variables 
referenced but not defined in your program. If you give more than one 
name, make sure the names are separated by spaces or plus signs (+). If 
you don’t supply filename extensions, the linker uses .lib by default. If 
you have more names than can fit on one line, type a plus sign (+) as the 
last character on the line and press the RETURN key. Link then prompts you 
for additional filenames. 


After entering all names, press the RETURN key. If you don’t want to search 
any libraries, don’t type any names; just press the RETURN key. 


Link now creates the executable file. 


When entering filenames, you must supply a pathname for any file that is not in 
the current drive and directory. You can use link options by typing them after 
the filename at any prompt. If the linker cannot find an object file, it displays a 
message and waits for you to change disks, if necessary. 


At any prompt, you can type the rest of the filenames by using the command 
line format described in the next section, "Method 2: Using a Command Line to 
Specify Link Files." 


You can also choose the default responses for all remaining prompts by typing 
a semicolon after any prompt, or you can type commas to indicate several files. 
(If you type a semicolon at the Object Modules prompt, be sure to supply at 
least one object filename.) When the linker encounters a semicolon, it 
immediately chooses the default responses and processes the remaining files 
without displaying any more prompts. 
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Example: 


The following example links the object modules moda.obj, modb.obj, 
modc.obj, and startup.obj; searches the library file math.lib on drive B of the 
Nib directory for routines and data used in the program; and creates an 
executable file named moda.exe, and a map file named abc.map. The /pause 
option in the Object Modules prompt line then causes link to pause while you 
change disks, after which the linker creates the executable file (see the section 
entitled "Pausing to Change Disks," later in this chapter): 


link 


Object Modules [.OBJ]: modatmodb+ 

Object Modules [.OBJ]: modct+startup/PAUSE 
Run File [moda.EXE]: 

List File [NUL.MAP]: abc 

Libraries [.LIB]: b:\lib\math 


Method 2: Using a Command Line to Specify Link Files 


You can also create an executable program by typing link, followed by the 
names of the files you wish to process. The command line has the following 
general form: 


link objectfiles [,[executablefile] [,[mapfile] 
[,[/ibraryfile]}]] [options] [;] 


The variables in this command line are described as follows: 


objectfiles Includes the name or names of object files that you want to 
link together. The files rnust have been created using 
MASM or a high-level-language compiler. The linker 
requires at least one object file. If you do not supply an 
extension, link provides the extension .obj. 


executablefiles Is an optional placeholder for the name you wish to give 
the executable file that link will create. If you do not 
supply an executablefile, link creates a filename by using 
the name of the first object file in the command line and 
appending it with an .exe extension. 
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mapfile Is the name of the file that receives the map listing. If you 
do not supply an extension, the linker provides the 
extension .map. If you specify the /map or /linenumbers 
option, the linker creates a map file even if you don’t 
specify one in your command line. 


libraryfiles Includes the name or names of the libraries containing 
routines that you wish to link to create a program. If you do 
not supply an extension, link supplies the extension lib. 


options Control the operation of link. You can use any of the 
options listed in the section entitled "The Link Options.” 
You can specify options anywhere on the command line. 


The commas you use to separate filenames for the different types of files are 
required even if you don’t supply a filename. If you want the filename for a file 
to be the default (the same as the base name of the first object file), you can 
type the comma that would follow the filename without actually supplying the 
filename. If you type the comma after the object file, link supplies the default 
name for the executablefile and suppresses the mapfile and libraryfiles. You 
can also use a semicolon anywhere after the object file to terminate the 
command line. 


If you do not supply all filenames in the command line and do not end the 
command line with a semicolon, the linker prompts you for additional files, 
using the prompts described previously in the section, "Method 1: Using 
Prompts to Specify Link Files." If you give more than one object file or library 
file, you must separate the names by spaces or plus signs. 


If you do not specify a drive or directory for a file, link assumes the file is on 
the current drive and directory. You cannot specify the drive or directory for 
the objectfile and expect link to supply the same drive and directory for other 
files. Instead, you must give the location of each file specifically. 


Note When linking modules produced by a high-level-language compiler that 
supports overlays, you must specify overlay modules by putting them in 
parentheses. Since MASM has no overlay manager, you can specify overlays 
only for object files linked with the run-time library of a language compiler that 
supports overlays. 
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For example, you can use overlays with modules compiled with Microsoft 
FORTRAN, versions 3.2 and later, Microsoft Pascal versions 3.2 and later, and 
Microsoft C versions 3.0 and later. See your language compiler’s manual for 
details on specifying overlays. 


Examples: 


The first example below uses the object file file.obj to create the executable 

file file.exe. Link searches the file.lib library for routines and variables used 
within the program. It also creates a file called file.map, which contains a list of 
the program’s segments and groups: 


link file.obj, file.exe, file.map, routine.lib 
The first example is equivalent to the following line: 
link file,,,routine 


The next example uses the two object files, startup.obj and file.obj, on the 
current drive to create an executable file named file.exe on drive B. Link 
creates a map file on the \ map directory of the current drive, but does not 
search any libraries: 


link startup+file,b:file, \map\file; 


The final example links the object modules moda.obj, modb.obj, modc.obj, and 
startup.obj: 


link moda modb modc startup/PAUSE,,abc,b:\lib\math 


The linker searches through the library file math.lib in the \ lib directory on 
drive B for routines and data used in the program. It then creates an executable 
file named moda.exe, and a map file named abc.map. 


The /pause option in the command line causes the linker to pause and ask you 
to change disks before it creates the executable file. (This option is described in 
more detail in the section "Pausing to Change Disks" later in this chapter.) 
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Method 3: Using a Response File to Specify Link Files 


You can create a program by listing, in a response file, the names of all the files 
to be processed, and by giving the name of the response file on the link 
command line. The simplest way to use a response file is with a command line 
of the following form: 


link @filename 


You can also specify a response file at any prompt, or at any position in a 
command line. The input from the response file is treated exactly as though you 
had typed it at the link prompts or in a command line. However, any 
RETURN/LINEFEED combinations in the file are treated the same as if you had 
pressed the RETURN key in response to a prompt, or typed a comma in a 
command line. 


When you specify a response file, remember that the filename must be the 
name of the response file, and that you must precede it by an "at" sign (@). If 
the file is in another directory or on another disk drive, you must provide a 
pathname. 


You can name the response file anything you like. The file content has the 
following general form: 


objectfiles 
[executablefile] 
[mapfile] 
[libraryfiles} 


You can omit any elements that have already been provided at prompts or from 
within a partial command line. 


You must place each group of filenames on a separate line. If you have more 
names than can fit on one line, you can simply continue the names on the next 
line by typing a plus sign as the last character in the current line and pressing 
the RETURN key. If you do not supply a filename for a group, you must leave an 
empty line. You can give options on any line. 

You can place a semicolon on any line in the response file. When link 
encounters the semicolon, it automatically supplies default filenames for all 
files you have not yet named in the response file. The remainder of the 
response file is ignored. 

When you create a program with a response file, the linker displays each 
response from your response file on the screen in the form of prompts. If the 
response file does not contain names for required files, link prompts you for the 
missing names and waits for you to enter responses. 
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Note A response file should end with either a semicolon (;) or a 
RETURN/LINEFEED combination. If you fail to provide a final RETURN/LINEFEED in the 
file, the linker will display the last line of the response file and wait for you to 
press the RETURN key. 


Example: 


The following response file tells the linker to link the four object modules, 
moda, modb, modc, and startup. Then, before producing the executable file 
moda.exe, it tells link to pause to let you swap disks. Finally, the linker creates 
a map file abc.map and searches the math.lib library in the \ lib directory of 
drive B: 


moda modb modc startup /PAUSE 
abc 
b:\lib\math 


The following procedure combines all three methods of supplying filenames. 
Assume you have a response file called library that contains one line: 


Lib1+1ib2+1ib3+1lib4 
Now start link with a partial command line: 
link objectl object2 


Link takes object] .obj and object2.obj as its object files, and prompts for the 
next file: 


Run File [object1.EXE]: exec 
List File [NUL.MAP]: 
Libraries [.LIB]: @library 


You include the name exec so that the linker will name the executable file 
exec.exe. You then press the RETURN key to indicate that no map file is desired, 
and you enter @library so that the linker will read in the response file 
containing the four library filenames. 


Link: A Linker 7.9 


The Lib Files 


You can direct link to search directories and disk drives for the libraries you 
have named in a command by either specifying one or more search paths with 
the library names, or by assigning the search paths to the environment variable 
LIB before you invoke link. Environment variables are explained under the set 
command in Chapter 3, "MS-DOS Commands." 


A search path is the path of a directory or drive name. You type search paths 
along with library names on the link command line or in response to the 
Libraries prompt. You can also specify up to 16 search paths and assign them 
to the LIB environment variable by using the MS-DOS set command. In the 
latter case, you must separate the search paths by semicolons (;). 

If you include a drive or directory name in the filename for a library in the link 
command line, the linker searches there only. If you don’t give a drive or 
directory name, link searches for library files in the following order: 


1. First, the linker searches the current drive and directory. 

2. If it doesn’t find the library there and you have specified one or more 
search paths in the command line, link searches the specified search paths 
in the order in which you gave them. 


3. If it still doesn’t find the library and you have set a search path by using 
the LIB environment variable, the linker searches there. 


4. If it still doesn’t find the library, link prints an error message. 


Examples: 


In the first example, the linker searches only the \ altlib directory on drive A to 
find the math.lib library. To find common_lib, it will search the current 
directory on the current drive, the current directory on drive B, and finally the \ 
lib directory on drive D: 


link file,,file,A:\altlib\math.1lib+common 
+B:+D:\lib\ 


In the second example, link searches the current directory, the \ lib directory on 
drive C, and the \ system\ lib directory on drive U to find the libraries, math.lib 
and common.lib: 


set LIB=C:\lib;U:\system\lib 
link file,,file.map,math+common 
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The Map File 


The map file lists the names, load addresses, and lengths of all segments in a 
program. It also lists the names and load addresses of any groups in the 
program, the program start address, and messages about any errors it may have 
encountered. If the /map option is used in the link command line, the map file 
lists the names and load addresses of all public symbols. 


Segment information has the general form shown in this example: 


Start Stop Length Name Class 
00000H 0172CH 0172DH TEXT CODE 
01730H 01E19H 006EAH DATA DATA 


The Start and Stop columns show the 20-bit addresses (in hexadecimal) of the 
first and last byte in each segment. These addresses are relative to the 
beginning of the load module, which is assumed to be address 0000H. The 
operating system chooses its own starting address once the program is actually 
loaded. The Length column gives the length of the segment in bytes; the Name 
column gives the name of the segment; and the Class column gives the 
segment’s class name. 


Group information has the following general form: 


Origin Group 
0000:0 IGROUP 
0173:0 DGROUP 


In this example, IGROUP is the name of the code (instruction) group and 
DGROUP is the name of the data group. 

At the end of the listing file, the linker gives you the address of the program 
entry point. 

If you specify the /map option in the link command line, the linker adds a 
public-symbol list to the map file. The symbols are presented twice: once in 
alphabetical order, then in the order of their load addresses. The list has the 
general form shown in the following example: 


Address Publics by Name 
0000:1567 BRK 

0000:1696 CHMOD 

0000:01DB CHKSTK 
0000:131C CLEARERR 


0173:0035 FAC 
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Address Publics by Value 
0000:01DB CHKSTK 

0000:131C CLEARERR 
0000:1567 BRK 

0000:1696 CHMOD 

0000:0035 FAC 


The addresses of the public symbols are in segment:offset format. They show 
the location of the symbol relative to the beginning of the load module, which 
is assumed to be at address 0000:0000. 


When the /high and /dsallocate options are used and the program’s code and 
data combined do not exceed 64K bytes, the map file may show symbols that 
have unusually large segment addresses. These addresses indicate a symbol 
whose location is below the actual start of the program code and data. 


For example, the following symbol entry shows that TEMPLATE is located 
below the start of the program: 


FFFO: 0A20 TEMPLATE 
Note that the 20-bit address of TEMPLATE is 00920H. 


The Temporary Disk File - Vm.tmp 


Link normally uses available memory for the link session. If it runs out of 
available memory, it creates a temporary disk file named vm.tmp in the current 
working directory. When the linker creates this file, it displays the following 
message: 


VM.TMP has been created. 
Do not change diskette in drive x: 


After this message appears, you must not remove the disk from the drive 
specified by x until the link session ends. The /pause option cannot be used if a 
temporary file is created. After link has created the executable file, it deletes 
the temporary file automatically. 


Note Do not use the vm.tmp filename for your own files, since when the 
linker creates the temporary file, it destroys any previous file that has the same 
name. 
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The Link Options 


The linker options specify and control the tasks that link performs. All options 
begin with the linker-option character, which is a slash (/). You can use the 
following options anywhere on a link command line: 


Option name 

/help 

/pause 

/exepack 

/map 

Ainenumbers 
/noignorecase 
/nodefaultlibrarysearch 
/stack 

/cparmaxalloc 


/high 

/dsallocate 
/nogroupassociation 
/overlayinterrupt 
/segments 

/dosseg 


Action 

Shows the list of options. 

Pauses during linking. 

Packs executable files. 

Creates a public-symbol map. 
Copies line numbers to a map file. 
Preserves case sensitivity in names. 
Overrides default libraries. 

Sets maximum allocation space. 


Sets the maximum number of 16-byte paragraphs 
needed by a program. 


Sets a high load address for a program. 
Allocates a data group. 

Sets a group association override. 

Sets an overlay interrupt. 

Sets a maximum number of segments. 
Specifies MS-DOS segment ordering. 


You can abbreviate an option name as long as your abbreviation contains 
enough letters to distinguish the specified option from other options. Minimum 
abbreviations are listed for each option. 


Many of the link options set values in the MS-DOS program header. You will 

understand these options better if you understand how the header is organized. 

The program header is described in the MS-DOS Programmer's Reference and 
in some reference books on MS-DOS. 
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Viewing the Options List 
Syntax: 


/help 


The /help option causes link to write a list of the available options to the 
screen. If you ever need a reminder of the available options, you may find this 
list convenient. You should not give a filename when using the /help option. 


Minimum abbreviation: /he 


Example: 


link /help 


Pausing to Change Disks 
Syntax: 


/pause 


The /pause option causes link to pause before writing the executable file to 
disk so that you can swap disks before the linker writes the executable (.exe) 
file to disk. 


If you specify the /pause switch, the linker displays the following message 
before creating the run file: 


About to generate .EXE file 
Change diskette in drive x: and press <ENTER> 


Note that x: is the proper drive name. This message appears after the linker has 
read data from the object files and library files, and after it has written data to 
the map file, if you specified one. Link resumes processing when you press the 
RETURN key, and after it writes the executable file to disk, it displays the 
following message: 


Please replace original diskette 
in drive letter and press <ENTER> 


Minimum abbreviation: /p 
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Note Do not remove the disk used for the vm.tmp file, if such a file has been 
created. If the temporary disk message appears when you have specified the 
/pause option, you should press CoNTROL-c to terminate the link session. 
Rearrange your files so that the temporary file and the executable file can be 
written to the same disk, then try again. 


Example: 


The following command causes the linker to pause just before creating the 
executable file file.exe. After creating this file, link pauses again to let you 
replace the original disk: 


link file/pause, file,,\lib\math 


Packing Executable Files 
Syntax: 


/exepack 


The /exepack option directs link to remove sequences of repeated bytes 
(typically nulls) and optimize the load-time relocation table before creating the 
executable file. Executable files linked with the /exepack option may be 
smaller, and, thus, load faster than files linked without the option. However, the 
Microsoft Symbolic Debug Utility (symdeb) cannot be used with packed files. 


The /exepack option does not always save a significant amount of disk space 
(in some cases it may even increase file size). Programs that have a large 
number of load-time relocations (about 500 or more) and long streams of 
repeated characters will usually be shorter if packed. If you are not sure if your 
program meets these conditions, try linking it both ways and compare the 
results. 


Minimum abbreviation: /e 
Example: 


This example creates a packed version of the file program.exe: 


link program /e; 
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Producing a Public-Symbol Map 


Syntax: 


/map 


The /map option causes link to produce a listing of all public symbols declared 
in your program. This list is copied to the map file that link creates. For a 
complete description of the listing-file format, see the section, "The Map File," 
earlier in this chapter. The /map option is required if you want to use symdeb 
for symbolic debugging. 


Minimum abbreviation: /m 


Note If you do not specify a map file in a link command, you can use the 
/map option to force the linker to create one. Link gives the forced map file the 
same filename as the first object file specified in the command. It also adds the 
default extension .map. 


Example: 


The following command creates a map of all public symbols in the file file.oby: 


link file,,/map; 


Copying Line Numbers to the Map File 
Syntax: 


flinenumbers 


The /linenumbers option directs the linker to copy the starting address of each 
program source line to a map file. The starting address is actually the address of 
the first instruction that corresponds to the source line. You can use the 
mapsym program to copy line number data to a symbol file, which can then be 
used by symdeb. 


The linker copies the line-number data only if you give a map-file name in the 
link command line, and only if the given object file has line-number 
information. Line numbering is available in some high-level-language 
compilers, including Microsoft FORTRAN and Pascal, versions 3.0 and later, 
and Microsoft C, versions 2.0 and later. 
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MASM does not copy line-number information to the object file. If an object 
file has no line-number information, the linker ignores the /linenumbers 
option. 

Minimum abbreviation: /li 


Note If you do not specify a map file in a link command, you can still use the 
Ainenumbers option to force the linker to create one. Just place the option at or 
before the List File prompt. Link gives the forced map file the same filename 
as the first object file that you specified in the command, and gives it the 
default extension .map. 


Example: 


This example causes the line-number information in the object file file.obj to be 
copied to the map file file.map: 


link file/linenumbers,,emt+slibfp 


Preserving Lowercase 
Syntax: 


/noignorecase 


The /noignorecase option directs link to treat uppercase and lowercase letters 
in symbol names as distinct letters. Normally, link considers uppercase and 
lowercase letters to be identical, treating the words "TWO," "two," and "Two" 
as the same symbol. When you use the /noignorecase option, however, the 
linker treats "TWO," "two," and "Two" as different symbols. 


Typically, you use the /noignorecase option with object files created by high- 
level-language compilers. Some compilers treat uppercase and lowercase letters 
as distinct letters and assume the linker does the same. 


If you are linking modules created with MASM to modules created with a case- 
sensitive language such as C, make sure public symbols have the same 
sensitivity in both modules. For example, you could make all variables in C 
distinctive by spelling, regardless of case, and then link without the 
/noignorecase option. Another alternative would be to use the /ML or MX 
option to make public variables in MASM case-sensitive. Then link with the 
/noignorecase option. 


Minimum abbreviation: /noi 
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Example: 


The following command causes the linker to treat uppercase and lowercase 
letters in symbol names as distinct letters. The object file file.obj is linked with 
routines from the standard C language library \ Slibc.lib located in the Vib 
directory. The C language expects uppercase and lowercase letters to be treated 
distinctly: 

link filel+file2/noi,,,em+mlibfp 


Ignoring Default Libraries 
Syntax: 


/nodefaultlibrarysearch 


The /nodefaultlibrarysearch option directs the linker to ignore any library 
names it may find in an object file. A high-level-language compiler may add a 
library name to an object file to ensure that a default set of libraries is linked 
with the program. Using this option overrides these default libraries and lets 
you explicitly name the libraries you want by including them on the link 
command line. 


Minimum abbreviation: /nod 


Example: 


The following example links the object files, startup.obj and file.obj, with 
routines from the libraries, em, slibfp, and slibc. Any default libraries that may 
have been named in startup.obj or file.obj are ignored: 


link startuptfile/nod,,,em+tslibfp+slibc 


Setting the Stack Size 
Syntax: 


/stack:size 


The /stack option sets the program stack to the number of bytes given by size. 
The linker usually calculates a program’s stack size automatically, basing it on 
the size of any stack segments given in the object files. If you do use the /stack 
option, the linker uses the value you type in place of any value it may have 
calculated. 
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The size can be any positive integer in the range from 1 to 65,535. This value 
can be a decimal, octal, or hexadecimal number. Octal numbers must begin 
with a zero, and hexadecimal numbers must begin with a leading zero followed 
by a lowercase x, for example, 0x/B. 


By using the exemod utility, you can also change the stack size after linking. 


Minimum abbreviation: /st 


Examples: 


The first example sets the stack size to 512 bytes: 

link file/stack:512,,; 

The second example sets the stack size to 255 (FFH) bytes: 
link moda+modb, run/st:0xFF,ab,\lib\start; 
The final example sets the stack size to 24 (30 octal) bytes: 


link startuptfile/st:030,,; 


Setting the Maximum Allocation Space 
Syntax: 
/cparmaxalloc:number 


The /eparmaxalloc option sets the maximum number of 16-byte paragraphs 
needed by a program when it is loaded into memory. The operating system uses 
this number when allocating space for a program prior to loading it. 


Link normally sets the maximum number of paragraphs to 65,535. Since this 
represents all addressable memory, the operating system always denies the 
default setting and allocates the largest contiguous block of memory it can find. 
If you use the /cparmaxalloc option, the operating system allocates no more 
space than is given by this option. This means any additional space in memory 
is free for other programs. 
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The number can be any integer in the range from 1 to 65,535. It must be a 
decimal, octal, or hexadecimal number. Octal numbers must begin with a zero, 
and hexadecimal values must begin with a leading zero followed by a 
lowercase x, for example, 0x2B. 


If number is less than the minimum number of paragraphs needed by the 
program, link ignores your request and sets the maximum value equal to the 
minimum needed. The minimum number of paragraphs needed by a program is 
never less than the number of paragraphs of code and data in the program. 


Minimum abbreviation: /c 


Examples: 


The first example sets the maximum allocation to 15 paragraphs: 

link file/c:15,,; 

The second example sets the maximum allocation to 255 (FFH) paragraphs: 
link modatmodb, run/cparmaxalloc:0xff,ab; 

The final example sets the maximum allocation to 24 (30 octal) paragraphs: 


link startup+file,/c:030,; 


Setting a High Start Address 


Syntax: 
/high 


The /high option sets a program's starting address to the highest possible 
address in free memory. If you don’t use the /high option, link sets the 
program’s starting address as low as possible in memory. 


Minimum abbreviation: /h 


Example: 


This example sets the starting address of the program in ftle.exe to the highest 
possible address in free memory: 


link startup+file/high,,; 
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Allocating a Data Group 
Syntax: 


/dsallocate 


The /dsallocate option directs the linker to reverse its normal processing when 
assigning addresses to items belonging to the group named DGROUP. 
Normally, link assigns the offset 0000H to the lowest byte in a group. If you 
use /dsallocate, link assigns the offset FFFFH to the highest byte in the group. 
The result is data that appear to be loaded as high as possible in the memory 
segment containing DGROUP. 

Typically, you use the /dsallocate option with the /high option to take 
advantage of unused memory before the start of the program. The linker 
assumes that all free bytes in DGROUP occupy the memory preceding the 
program. To use the group, you must set a segment register to the start address 
of DGROUP. 


Minimum abbreviation: /d 


Example: 


The following example directs the linker to place the program as high in 
memory as possible, then adjust the offsets of all data items in DGROUP so 
that they are loaded as high as possible within the group: 


link startupt+file/high/dsallocate,,,em+mlibfp 


Removing Groups from a Program 
Syntax: 


/nogroupassociation 


The /nogroupassociation option directs link to ignore group associations when 
assigning addresses to data and code items. 


Minimum abbreviation: /nog 


Note This option exists strictly for compatibility with older versions of 
FORTRAN and Pascal (Microsoft versions 3.13 or earlier, or any IBM version 
prior to 2.0). You should never use the /nogroupassociation option except to 
link with object files produced by those compilers, or with the run-time 
libraries that accompany the old compilers. 
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Setting the Overlay Interrupt 
Syntax: 
/overlayinterrupt:number 


The /overlayinterrupt option sets the interrupt number of the overlay loading 
routine to number. This option overrides the normal overlay interrupt number 


(03FH). 


Number can be any integer value in the range from 0 to 255. It must be a 
decimal, octal, or hexadecimal number. Octal numbers must have a leading 
zero, and hexadecimal numbers must start with a leading zero followed by a 
lowercase x, for example, 0x3B. 


MASM does not have an overlay manager. Therefore, you can use this option 
only if you are linking with a run-time module from a language compiler that 
supports overlays. Check your compiler documentation, since you may not be 
able to use this option with some compilers. 


Minimum abbreviation: /o 


Note You should not use interrupt numbers that conflict with the standard 
MS-DOS interrupts. 


Examples: 


The first example sets the overlay interrupt number to 255: 

link file/o:255,,,87+slibfp 

The second example sets the overlay interrupt number to 255 (FFH): 
link modatmodb, run/overlay:0xff,ab.map,em+tmlibfp 
The final example sets the overlay interrupt number to 255 (377 octal): 


link startupt+file, /o:0377,,em+tmlibfp 
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Setting the Maximum Number of Segments 
Syntax: 
/segments:number 


The /segments option directs the linker to process no more than number 
segments per program. If it encounters more than the given limit, the linker 
displays an error message, and stops linking. You use this option to override 
the default limit of 128 segments. 


If you do not use /segments, the linker allocates enough memory space to 
process up to 128 segments. If your program has more than 128 segments, you 
will need to set the segment limit higher to increase the number of segments 
that link can process. If you get the following link error message, you should 
set the segment limit lower: 


Segment limit set too high 


The number can be any integer value in the range from 1 to 1024. It must be a 
decimal, octal, or hexadecimal number. Octal numbers must have a leading 
zero, and hexadecimal numbers must start with a leading zero followed by a 
lowercase x, for example, 0x4B. 


Minimum abbreviation: /se 


Examples: 


The first example sets the segment limit to 192: 
link file/se:192,,; 
The second example sets the segment limit to 255 (FFH). 


link moda+modb, run/segments:0xff,ab,em+mlibfp; 


Using DOS Segment Order 

Syntax: 

/dosseg 

The /dosseg option causes link to arrange all segments in the executable file 


according to the MS-DOS segment-ordering convention. This convention has 
the following rules: 
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e All segments having the class name CODE are placed at the beginning of 
the executable file. 


e Any other segments that do not belong to the group, DGROUP, are placed 
immediately after the CODE segments. 


e All segments belonging to DGROUFP are placed at the end of the file. 


If you do not use the /dosseg option, see the section, "Order of Segments," later 
in this chapter, for an explanation of the normal segment order. 


Minimum abbreviation: /do 


Example: 


The following command causes the linker to create an executable file, named 
file.exe, whose segments are arranged according to the MS-DOS segment- 
ordering convention. The segments in the object files start.obj and test.obj, and 
any segments copied from the libraries math.lib and common.lib, are arranged 
according to the same segment-ordering convention as above. 


link start+test/dosseg,,,math+common 


How Link Works 


Link creates an executable file by concatenating a program’s code and data 
segments according to the instructions in the original source files. These 
concatenated segments form an executable image that is copied directly into 
memory when you run the program. The order and manner in which the linker 
copies segments to the executable file defines the order and manner in which it 
loads the segments into memory. 

You can tell the linker how to link a program’s segments by using a 
SEGMENT directive to supply segment attributes, or by using the GROUP 
directive to form segment groups. These directives define group associations, 
classes, and align and combine types that define the order and relative starting 
addresses of all segments in a program. This information works in addition to 
any information you supply through command line options. 


The following sections explain the process that link uses to concatenate 
segments and resolve references to items in memory. 
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Alignment of Segments 


The linker uses a segment’s align type to set the starting address for the 
segment. The align types are byte, word, para, and page. These types 
correspond to starting addresses at byte, word, paragraph, and page boundaries, 
representing addresses that are multiples of 1, 2, 16, and 256, respectively. The 
default align type is para. 


When the linker encounters a segment, it checks the align type before copying 
the segment to the executable file. If the align type is word, para, or page, the 
linker checks the executable image to see if the last byte copied ends at an 
appropriate boundary. If it doesn’t, link pads the image with extra null bytes. 


Frame Number 


The linker computes a starting address starting for each segment in a program. 
The addresses starting address is based on a segment’s align type and on the 
size of the segments already copied to the executable file. The address consists 
of an offset and a canonical frame number, which specifies the address of the 
first paragraph in memory that contains one or more bytes of the segment. A 
frame number is always a multiple of 16 (a paragraph address), and the offset is 
the number of bytes from the start of the paragraph to the first byte in the 
segment. For byte and word align types, the offset may be nonzero, but the 
offset is always zero for para and page align types. 

The frame number of a segment can be obtained from a link file. The frame 
number is the first five hexadecimal digits of the start address specified for the 
segment. 


Order of Segments 


Link copies segments to the executable file in the same order that it encounters 
them in the object files. The linker maintains this order throughout the program 
unless it encounters two or more segments with the same class name. Segments 
with identical class names belong to the same class type, and are ordered 
contiguously. 

The Microsoft Macro Assembler Reference Manual includes a more detailed 
discussion of segment loading order and methods of controlling loading order 
by assigning class types. 
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Combined Segments 


Link uses combine types to determine whether two or more segments sharing 
the same name should be combined into a single large segment. The combine 
types are public, stack, common, memory, at, and private. Combine types are 
also described in the Microsoft Macro Assembler Reference Manual. 


If a segment has a public combine type, the linker automatically combines it 
with any other segments that have the same name and belong to the same class. 
When link combines segments, it ensures that the segments are contiguous and 
that all addresses in the segments can be accessed using an offset from the same 
frame address. The result is the same as if the segment were defined as a whole 
in the source file. 


The linker preserves each segment’s align type. This means that even though 
the segments belong to a single, large segment, the code and data in the 
segments retain their original align type. If the combined segments exceed 64K 
bytes, link displays an error message. 


If a segment has a stack combine type, the linker carries out the same combine 
operation as for public segments. The only difference is that stack segments 
cause link to copy an initial stack-pointer value to the executable file. This 
stack-pointer value is the offset to the end of the first stack segment (or 
combined stack segment) that the linker encounters. 


If you use the stack type for stack segments, you do not need to give 
instructions to load the segment into the SS register. 


If a segment has a common combine type, the linker combines it automatically 
with any other segments that have the same name and belong to the same class. 
When link combines common segments, however, it places the start of each 
segment at the same address, creating a series of overlapping segments. The 
result is a single segment no larger than the largest of the combined segments. 


The linker treats segments with memory combine types exactly like segments 
with public combine types. The Microsoft Macro Assembler (MASM), 
provides combine type memory for compatibility with linkers that support a 
separate combine type for memory segments. 


A segment has a private combine type only if no explicit combine type is 
defined types for it in the source file. Link does not combine private segments. 
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Groups 


Groups permit noncontiguous segments that do not belong to the same class to 
be addressable relative to the same frame address. When link encounters a 
group, it adjusts all memory references to items in the group so that they are 
relative to the same frame address. 


Segments in a group do not have to be contiguous and do not have to belong to 
the same class. Nor do they have to have the same combine type. The only 
requirement is that all segments in the group fit within 64K bytes. 


Groups do not affect the order in which the segments are loaded. Unless you 
use class names and enter object files in the right order, there is no guarantee 
that the segments will be contiguous. In fact, the linker may place segments 
that do not belong to the group in the same 64K bytes of memory. Although 
link does not explicitly check whether all segments in a group fit within this 
64K of memory, the linker is likely to encounter a fixup-overflow error if this 
requirement is not met. 


Groups, and how to define them, are discussed further in the Microsoft Macro 
Assembler Reference Manual. 


Fixups 


Once the starting address of each segment in a program is known, and all 
segment combinations and groups have been established, the linker can fix up 
any unresolved references to labels and variables. To fix up unresolved 
references, the linker computes an appropriate offset and segment address and 
replaces the temporary values, generated by the assembler, with the new values. 


Link carries out fixups for four different references: 


e Short 

e Near self-relative 

e Near segment-relative 
e Long 


The size of the value to be computed depends on the type of reference. If link 
discovers an error in the anticipated size of a reference, it displays a fixup- 
overflow message. This error can happen, for example, if a program attempts, 
by using a 16-bit offset, to reach an instruction in a segment that has a different 
frame address. The error can also occur if the segments in a group do not fit 
within a single 64K-byte block of memory. 
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A short reference occurs in JMP instructions that attempt to pass control to 
labeled instructions in the same segment or group. The target instruction must 
be no more than 128 bytes from the point of reference. The linker computes a 
signed, 8-bit number for this reference and displays an error message if the 
target instruction belongs to a different segment or group (that is, if it has a 
different frame address), or if the target is more than 128 bytes distant (in either 
direction). 

A near self-relative reference occurs in instructions which access data relative 
to the same segment or group. The linker computes a 16-bit offset for this 
reference and displays an error message if the data are not in the same segment 
or group. 

A near segment-relative reference occurs in instructions that attempt to access 
data in a specified segment or group, or that is relative to a specified segment 
register. Link computes a 16-bit offset for this reference and displays an error 
message if either of the following conditions exists: the offset of the target 
within the specified frame is greater than 64K bytes or less than 0, or the 
beginning of the canonical frame of the target is not addressable. 


A long reference occurs in CALL instructions that attempt to access an 
instruction in another segment or group. Link computes a 16-bit frame address 
and 16bit offset for this reference and displays an error message if either of the 
following conditions exists: the computed offset is greater than 64K bytes or 
less than 0, or the beginning of the canonical frame of the target is not 
addressable. 


In this chapter, you've learned how to use link to create MS-DOS executable 
files. You’ve also learned how to use link command options, and some details 
about how link works. In the next chapter, "Debug," you'll learn how to use the 
debug utility when writing or testing binary (.com or .exe) executable object 
files. 


8 Debug 


In this chapter, you will learn 


e How to start the debug utility 
e How to use the debug commands and parameters 


Note You need to read this chapter only if you are writing or testing 
executable programs (.com or .exe files) or object (.ob/) files. 


Introduction 


The debug utility is a debugging program that provides a controlled testing 
environment for binary and executable object files. Note that Edlin, the MS- 
DOS line editor, is used to alter source files; debug is Edlin’s counterpart for 
binary files. 

Debug eliminates the need to reassemble a program to see if a problem has 
been fixed by a minor change. It allows you to alter the contents of a file or the 
contents of a CPU register, and then immediately reexecute a program to check 
the validity of the changes made. 


All debug commands may be aborted at any time by pressing contRoL-c. The 
CONTROL-S key sequence suspends the display, so that you can read it before the 
output scrolls away. Pressing any key other than CONTROL-C Or CONTROLS restarts 
the display. All these commands are consistent with the control character 
functions available at the MS-DOS command level. 
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How to Start Debug 


Debug may be started two ways. By the first method, you type all commands in 
response to the debug prompt (a hyphen). By the second method, you type all 
commands on the line used to start debug. 


Method 1: debug: 
Method 2: debug [filename [arglist]]: 


Method 1: Debug 


To start debug using method 1, simply type the following: 
debug 


Debug responds with the hyphen (-) prompt, signaling that it is ready to accept 
your commands. Since you didn’t specify a filename, you can use other 
commands to work on current memory, disk sectors, or disk files. 


Warnings 

e When debug (version 3.0) is started, it sets up a program header at offset 0 
in the program work area. In previous versions of debug, you could 
overwrite this header. You can still overwrite the default header if you 
don’t give a filename to debug. If you are debugging a .com or .exe file, 
however, do not tamper with the program header below address 5CH, or 
debug will terminate. 


e Do not restart a program after the following message is displayed: 
Program terminated normally 


You must reload the program with the N (name) and L (load) commands 
for it to run properly. 
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Method 2: Command Line 


To start debug using a command line, you must use the following syntax: 
debug [filename [arglist]] 


For example, if you specify a filename, the following would be a typical 
command to start debug: 


debug file.exe 


Debug would then load file.exe into memory starting at 100 (hexadecimal) in 
the lowest available segment. The BX:CX registers are loaded with the number 
of bytes placed into memory. 

If you do include a filename, you might also specify an arglist. An arglist is a 
list of filename parameters and switches that are to be passed to the program 
filename. So when filename is loaded into memory, it is loaded as if it had been 
started with a command of the form, debug filename arglist. 


Here, filename is the file to be debugged, and arglist is the rest of the command 
line used when debug calls and loads filename into memory. 


Debug Command Information 


Each debug command consists of a single letter followed by one or more 
parameters. Additionally, the control characters and special editing functions 
described in Chapter 5, "MS-DOS Editing and Function Keys," apply to debug 
as well. 

If a syntax error occurs in a debug command, debug reprints the command line 
and indicates the error with a caret (^) and the word "Error" as in the following 
example, 


dcs:100 cs:110 
“ Error 


Note that when typing commands and parameters you may use any 
combination of uppercase and lowercase letters. 


The debug commands are listed below. Following this list, the commands and 
their parameters are described in greater detail. 


8.4 MS-DOS User's Reference 


Debug command 

A [address] 

C range address 

D [range] 

E address [list] 

F range list 

G [=address [address...}]} 
H value value 

I value 

L [address [drive:record record]] 
M range address 

N filename [filename] 

O value byte 

Q 

R [register-name] 

S range list 

T [=address] [value] 

U [range] 


W [address [drive:record record]]| 


Function 
Assemble 
Compare 
Dump 
Enter 

Fill 

Go 

Hex 
Input 
Load 
Move 
Name 
Output 
Quit 
Register 
Search 
Trace 
Unassemble 
Write 


Debug Command Parameters 


All debug commands accept parameters, except the Q (quit) command. 
Parameters may be separated by delimiters (spaces or commas), but a delimiter 
is required only between two consecutive hexadecimal values. Thus, the 


following commands are equivalent: 


dcs:100 110 
d cs:100 110 
d,cs:100,110 


Parameter 
drive: 


byte 


record 


value 


address 


range 
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Definition 
A one-digit hexadecimal value that indicates which drive a 


file will be loaded from or written to. The valid values are 
0—3, where 0=A:, 1=B:, 2=C:, 3=D:. 


A two-digit hexadecimal value placed in or read from an 
address or register. 


One-digit to three-digit hexadecimal value that indicates 
the logical record number on the disk and the number of 
disk sectors to be written or loaded. Logical records 
correspond to sectors; however, since they represent the 
entire disk space, their numbering differs. 

A hexadecimal value of up to four digits that specifies a 
port number or the number of times a command should 
repeat its functions. 


A two-part designation containing either an alphabetic 
segment register or a four-digit segment address plus an 
offset value. You may omit the segment name or segment 
address, in which case the default segment DS is used for 
all commands except G, L, T, U, and W, for which the 
default segment is CS. All numeric values are hexadecimal. 


Following is an example address: 


CS:0100 
04BA: 0100 


Note that the colon is required between the segment name 
(whether numeric or alphabetic) and the offset value. 


Contains two addresses: for example, address address; or 
one address, an L, and a value: for example, address L 
value where value is the number of lines on which the 
command should operate (L80 is assumed). The second 
type of range cannot be used if another hexadecimal value 
follows, since the hexadecimal value would be interpreted 
as the second address of the range. 
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list 


string 


Here are some example ranges: 


CS$:100 110 
CS:100 L 10 
CS:100 


The following example, however, is illegal: 


cCS:100 CS:110 
b Error 


The limit for range is 10000 (hexadecimal). To specify a 
value of 10000 with only four digits, type 0000 (or 0). 


A series of byte values or strings. List must be the last 
parameter on the command line. 


Following is an example list: 
fcs:100 42 45 52 54 41 


Any number of characters enclosed in quotation marks. The 
quotation marks may be either single (’ °) or double (" "). If 
the delimiter marks must appear within a string, you must 
use the double quotation marks. 


For example, the following strings are legal: 


"This ‘string’ is okay." 
"This ""string"" is okay." 


However, this string is illegal: 
""This "string" is not okay."" 


Note that the double quotation marks are not necessary in 
the following strings: 


"This ‘’string’’ is not necessary." 
‘This ""string"" is not necessary.’ 


The ascu values of the characters in the string are used as a 
list of byte values. 
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Assemble 
Purpose: 


Assembles 8086/8087/8088 mnemonics directly into memory. 
Syntax: 


A[address] 


Comments: 


If it finds a syntax error, debug responds with the following message, then 
redisplays the current assembly address: 


“Error 


All numeric values are hexadecimal and you must type them as 14 characters. 
Also, you must specify prefix mnemonics in front of the opcode to which they 
refer. You may type them on a separate line, however. 


The segment override mnemonics are CS:, DS:, ES:, and SS:. The mnemonic 
for the far return is RETF. String manipulation mnemonics must explicitly 
state the string size. For example, use MOVSW to move word strings, and use 
MOVSB to move byte strings. 


The assembler will automatically assemble short, near, or far jumps and calls, 
depending on byte displacement, to the destination address. You may override 
these jumps and calls by using a NEAR or FAR prefix, as in the following 
example: 


0100:0500 JMP 502 ; a 2-byte short jump 
0100:0502 JMP NEAR 505 ; a 3~-byte near jump 
0100:505 JMP FAR 50A ; a 5-byte far jump 


You may abbreviate the NEAR prefix to NE, but the FAR prefix cannot be 
abbreviated. 


Debug cannot tell whether some operands refer to a word memory location or 
to a byte memory location. In this case, the data type must be explicitly stated 
with the prefix, WORD PTR or BYTE PTR. Acceptable abbreviations are 
WO and BY. For example, 


NEG BYTE PTR [128] 
DEC wo [SI] 
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Debug also cannot tell whether an operand refers to a memory location or to an 
immediate operand. So it uses the common convention that operands enclosed 
in square brackets refer to memory. For example, 


MOV AX,21 ; Load AX with 21H 
MOV AX,[21] ; Load AX with the 
; contents 
; of memory location 21H 
Two popular pseudo-instructions are available with the A (assemble) 
command: the DB opcode, which assembles byte values directly into memory; 


and the DW opcode, which assembles word values directly into memory. 
Following are examples of both: 


DB 1,2,3,4,"THIS IS AN EXAMPLE" 
DB ‘THIS IS A QUOTATION MARK: "’ 
DB “THIS IS A QUOTATION MARK: ’" 
DW 1000, 2000, 3000, "BACH" 


The A command supports all forms of register indirect commands. For 
example, 


ADD BX, 34[BP+2] . [SI-1] 
POP [BP+DI] 
PUSH {SI} 


All opcode synonyms are also supported, as in the next example: 


LOOPZ 100 
LOOPE 100 
JA 200 
JNBE 200 


For 8087 opcodes, the WAIT or FWAIT prefixes must be explicitly specified, 
as in these last examples: 


FWAIT FADD ST,ST(3) ; This line assembles 
; an FWAIT prefix 
LD TBYTE PTR [BX] ; This line does not 
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Compare 
Purpose: 
Compares the portion of memory specified by range to a portion of the same 


size beginning at the specified address. 


Syntax: 


Crange address 


Comments: 


If the two areas of memory are identical, there is no display, and debug returns 
with the MS-DOS prompt. If there are differences, they are displayed in this 
format: 


addressI bytel byte2 address2 


Example: 


The following commands have the same effect: 


C100,1FF 300 
Or: 
C100L100 300 


Each command compares the block of memory from 100 to 1FFH with the 
block of memory from 300 to 3FFH. 
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Dump 
Purpose: 


Displays the contents of the specified range of memory. 


Syntax: 


D[range] 


Comments: 


If you specify a range of addresses with the D (dump) command, the contents 
of the range are displayed. If you don’t use parameters with the D command, 
128 bytes are displayed at the first address (DS:100) after the address displayed 
by the previous D command. 

The dump is displayed in two portions: a hexadecimal dump (each byte is 
shown in hexadecimal value) and an ascu dump (the bytes are shown in Ascii 
characters). Nonprinting characters are denoted by a period (.) in the asc 
portion of the display. Each display line shows 16 bytes, with a hyphen 
between the eighth and ninth bytes. Each displayed line begins on a 16-byte 
boundary. At times in this chapter, displays are split to fit them on the page. 


Examples: 


If you type the command 

des:100 110 

debug displays the dump in the following format: 

04BA:0100 42 45 52 54 41 ... 4E 44 TOM SAWYER 


If you simply type the D command, the display is formatted as just described. 
Each line of the display begins with an address incremented by 16 from the 
address on the previous line. 


Each subsequent D (typed without parameters) displays the bytes immediately 
following those last displayed. 
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If you type the following command, the display is formatted as described 
above, but 20H bytes are displayed: 


DCS:100 L 20 


If you then type the following command, the display is formatted as described 
above, but all the bytes in the range of lines from 100H to 115H in the CS 
segment are displayed: 


DCS:100 115 
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Enter 
Purpose: 


Enters byte values into memory at the specified address. 


Syntax: 


Eaddress{list] 


Comments: 


If, when using the E (enter) command, you type the optional list of values, the 
byte values are replaced automatically. (If an error occurs, no byte values are 
changed.) 

If you type the address without the optional list, debug displays the address 
and its contents, repeats the address on the next line, and then waits for your 
input. At this point, the E (enter) command waits for you to perform one of the 
following actions: 


è Replace a byte value with a value you type. Simply type the value after the 
current value. If the one you type is not a legal hexadecimal value or if it 
contains more than two digits, the illegal or extra character is not echoed. 


° Press the seaœ»par to advance to the next byte. To change the value, 
simply type the new value as described in the previous action. If when you 
press the sPaceBar, you move beyond an 8-byte boundary, debug starts a 
new display line with the address displayed at the beginning. 

e Type a hyphen (-) to return to the preceding byte. If you decide to change 
a byte behind the current position, typing the hyphen returns the current 
position to the previous byte. When you type the hyphen, a new line is 
started with its address and byte value displayed. 

e Press the RETuRN key to terminate the E command. The reTURN key may be 
pressed at any byte position. 
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Examples: 


Suppose you type the following command: 

ECS:100 

Now suppose that debug displays the following: 

04BA:0100 EB. _ 

To change this value to, say, 41, type the number 41 at the cursor, as shown: 
04BA:0100 EB.41_ 


To step through the subsequent bytes, you would press the sPACEBAR until you 
saw the following: 


04BA:0100 EB.41 10. 00. BC. _ 


To change BC to the number 42, for instance, you would type the number at 
the cursor, as follows: 


04BA:0100 EB.41 10. 00. BC.42_ 


Notice that the value 10 should be 6F. To correct this value, you would type the 
hyphen as many times as needed to return to byte 0101 (value 10), then replace 
10 with 6F: 


04BA:0100 EB.41 10. 00. BC.42 
O4BA:0102 00.-_ 
O4BA:0101 10.6F_ 


Pressing the RETURN key ends the E command and returns you to the debug 
command level. 
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Fill 
Purpose: 


Fills the addresses in the specified range with the values in the specified list. 


Syntax: 


Frange list 


Comments: 


If the range contains more bytes than the number of values in the ist, the list 
will be used repeatedly until all bytes in the range are filled. 


If the dist contains more values than the number of bytes in the range, the extra 
values in the list are ignored. If any of the memory in the range is not valid 
(bad or nonexistent), the error will occur in all succeeding locations. 


Example: 


Suppose you type the following command: 
FO4BA:100 L 100 42 45 52 54 41 


In response, debug would fill memory locations 04BA:100 through 04BA:1FF 
with the bytes specified. The five values would then be repeated until all the 
100H bytes were filled. 
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Go 


Purpose: 


Executes the program currently in memory. 


Syntax: 
G[=address [addresses]] 


Comments: 


If you type the G (go) command by itself, the program currently in memory 
executes as if it had run outside debug. 

If you set =address, execution of the G command begins at the address 
specified. The equal sign (=) is required so that debug can distinguish the start 
=address from the breakpoint addresses. 

With the other optional addresses set, execution stops at the first address 
encountered, regardless of that address’ position in the list of addresses that halt 
execution or program branching. When program execution reaches a 
breakpoint, the registers, flags, and decoded instruction are displayed for the 
last instruction executed. The result is the same as if you had typed the R 
(register) command for the breakpoint address. 


You may set up to ten breakpoints, but only at addresses containing the first 
byte of an 8086 opcode. If you set more than ten breakpoints, debug returns the 
BP error message. 


The user stack pointer must be valid and must have 6 bytes available for this 
command. The G command uses an IRET instruction to cause a jump to the 
program under test. The user stack pointer is set, and the user flags, code 
segment register, and instruction pointer are pushed on the user stack. (If the 
user stack is not valid or is too small, the operating system may crash.) An 
interrupt code (OCCH) is placed at the specified breakpoint address(es). 


When debug encounters an instruction with the breakpoint code, it restores all 
breakpoint addresses to their original instructions. If you don’t halt execution at 
one of the breakpoints, the interrupt codes are not replaced with the original 
instructions. 
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Example: 


Suppose you type the following command: 


GCS:7550 


The program currently in memory would execute up to the address 7550 in the 
CS segment. Debug would then display registers and flags, after which the G 
command would terminate. 

After debug has encountered a breakpoint, if you type the G command again 
the program runs as if you had typed the filename at the MS-DOS command 
level. The only difference is that program execution begins at the instruction 
after the breakpoint, rather than at the usual start address. 
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Hex 
Purpose: 


Performs hexadecimal arithmetic on the two specified parameters. 


Syntax: 


Hvalue value 


Comments: 


First, debug adds the two parameters, then subtracts the second parameter from 
the first. The results of these actions are displayed on one line—first the sum, 
then the difference. 


Example: 


Suppose you type the following command: 
H19F 10A 


In response, debug would perform the calculations and then display the 
following result: 


O2A9 0095 
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Input 
Purpose: 


Inputs and displays one byte from the port specified by value. 


Syntax: 


Tvalue 


Comment: 


A 16-bit port address is allowed. 


Example: 


Suppose you type the following command: 
I2F8 


Suppose also that the byte at the port is 42H. Debug would input the byte and 
then display the following: 


42 
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Load 
Purpose: 


Loads a file into memory. 
Syntax: 


L[ address [drive: record record] ]| 


Comments: 


Set BX:CX to the number of bytes read. The file must have been named either 
when you started debug or with the N (name) command. Both the debug 
invocation and the N command format a filename properly in the normal 
format of a file control block at CS:5C. 


If you use the L (load) command without any parameters, debug loads the file 
into memory beginning at address CS:100 and sets BX:CX to the number of 
bytes loaded. If you type the L command with an address parameter, loading 
begins at the memory location specified by the address. If you use the L 
command with all parameters included, absolute disk sectors are loaded, 
instead of a file. 


Each record is taken from the specified drive: (the drive name is numeric: 
0=A:, 1=B:, 2=C:, etc.). Debug begins loading with the first specified record, 
and continues until the number of sectors in the second record have been 
loaded. 


Example: 


Suppose once you have started debug that you type the following commands: 
-NFILE.COM 


Now, to load file.com, you would simply type the L command. 


Debug would then load the file and display the debug prompt. Suppose now 
that you want to load only portions of a file or certain records from a disk. To 
do this, you would type the following: 


LO4BA:100 2 OF 6D 


Debug would then load 109 (6D hex) records, beginning with logical record 
number 15, into memory beginning at address 04BA:0100. Then once it had 
loaded the records, debug would simply return the hyphen (-) prompt. 
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If the file has an .exe extension, it would be relocated to the load address 
specified in the header of the .exe file. The address parameter is always ignored 
for .exe files. The header itself is stripped off the .exe file before it is loaded 
into memory. So, the size of an .exe file on disk will differ from its size in 
memory. 


If the file was named by the N (name) command, or specified when you started 
debug, as a .hex file, then typing the L command with no parameters would 
cause debug to load the file beginning at the address specified in the .hex file. 
If the L command included the option address, debug would add the address 
specified in the L command to the address found in the .hex file to determine 
the start address at which to load the file. 
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Move 
Purpose: 


Moves the block of memory specified by range to the location beginning at the 
specified address. 


Syntax: 


Mrange address 


Comments: 


Overlapping moves (i.e., moves where part of the block overlaps some of the 
current addresses) are always performed without loss of data. Addresses that 
could be overwritten are moved first. For moves from higher to lower 
addresses, the sequence of events is to first move the data beginning at the 
block’s lowest address and then work toward the highest. For moves from 
lower to higher addresses, the sequence is to first move the data beginning at 
the block’s highest address and then work toward the lowest. 

Note that if the addresses in the block being moved will not have new data 
written to them, the data in the block before the move will remain. The M 
(move) command copies the data from one area into another, in the sequence 
described, and writes over the new addresses. This action is why the sequence 
of the move is important. 


Example: 


Suppose you type the following command: 
MCS:100 110 CS:500 


In response, debug would first move address CS:110 to CS:510, then CS:10F 
to CS:50F, and so on until it has moved CS:100 to CS:500. To review the 
results of the move, you could type the D (dump) command, using the same 
address you used with the M command. 
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Name 


Purpose: 


Sets filenames. 


Syntax: 


Nfilename [filename...] 


Comments: 


The N (name) command performs two functions. First, it assigns a filename for 
a later L (load) or W (write) command. So if you start debug without naming a 
file to be debugged, you must type the command Nfilename before a file can be 
loaded. Second, the N command assigns filename parameters to the file being 
debugged. In this case, N accepts a list of parameters used by the file being 
debugged. 


Note that these two functions overlap. Consider, for example, the following set 
of debug commands: 


-NF ILE] .EXE 
-L 
-G 


The N command would use these commands to perform the following steps: 
1. It would first assign the filename file/ .exe to the file to be used in any later 
L or W commands. 


2. It would also assign the file/.exe filename to the first filename parameter 
used by any program that is later debugged. 


3. The L command would then load file! .exe into memory. 
4. The G (go)command would cause file! .exe to be run with file] .exe as the 


single filename parameter (that is, file .exe would be run as if file! .exe 
had been typed at the command level). 


A more useful chain of commands might look like this: 
-NFILE1 .EXE 

-L 

-NFILE2.DAT FILE3.DAT 

-G 
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In this example, the N command sets file] .exe as the filename for the 
subsequent L command, which loads filel.exe into memory. The N command is 
then used again, this time to specify the parameters to be used by file/.exe. 
Finally, when the G command is run, file/.exe is executed as if file! file2.dat 
file3 dat had been typed at the MS-DOS command level. 


Note that if you were to execute a W command now, then file! .exe--the file 
being debugged--would be saved with the name file2.dat. To avoid this kind of 
result, you should always execute an N command before either an L or W 
command. 


There are four regions of memory that can be affected by the N command: 


Memory 

location Contents 

CS:5C FCB for file 1 
CS:6C FCB for file 2 
CS:80 Count of characters 
CS:81 All characters typed 


The first filename parameter that you specify for the N command has a file 
control block (FCB) set up at CS:5C. If you name a second filename parameter, 
an FCB is set up for this parameter beginning at CS:6C. The number of 
characters typed in the N command (exclusive of the first character, N) is given 
at location CS:80. 


The actual] stream of characters given by the N command (again, exclusive of 
the letter N) begins at CS:81. Note that this stream of characters may contain 

switches and delimiters that would be legal in any command typed at the MS- 
DOS command level. 


Example: 


A typical use of the N command is as follows: 


DEBUG PROG.COM 
-NPARAM1 PARAM2/C 
-G 


In this case, the G command executes the file in memory as if you had typed 
the following command line: 


PROG PARAM1 PARAM2/C 


Testing and debugging therefore reflect a normal run-time environment for 
prog.com. 
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Output 
Purpose: 


Sends the specified byte to the output port specified by value. 


Syntax: 


Ovalue byte 


Comment: 


A 16-bit port address is allowed. 


Example: 


Suppose you want to debug to output the byte value 4F to output port 2F8. To 
do this, you could simply type the following command: 


O2F8 4F 
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Quit 
Purpose: 


Terminates the debug utility. 


Syntax: 
Q 


Comments: 


The Q (quit) command takes no parameters and exits debug without saving the 
file you’re currently working with. You are returned to the MS-DOS command 
level. 


Example: 


To end the debugging session, simply type the following and press the RETURN 
key: 


q 


Debug terminates, and control retums to the MS-DOS command level. 
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Register 
Purpose: 


Displays the contents of one or more CPU registers. 


Syntax: 


R[register-name] 


Comments: 


If you do not type a register-name, the R (register) command dumps the 
register storage area and displays the contents of all registers and flags. 


If you do type a register-name, the 16-bit value of that register is displayed in 
hexadecimal, and a colon then appears as a prompt. You can now either type a 
value to change the register, or press the RETURN key if you don’t want a change. 


Following is a list of the valid register-names: 


AX BP SS 

BX SI CS 

CX DI IP (IP and PC both refer 
Dx DS PC to the instruction pointer) 
SP ES F 


Any other entry for register-name results in a BR error message. 


If you type F as the register-name, debug displays each flag with a two- 
character alphabetic code. To change any flag, type the opposite two-letter 
code. The flags are then either set or cleared. 
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The flags are listed below with their codes for SET and CLEAR: 


Flag name Set Clear 
Overflow OV NV 

Direction DN (Decrement) UP (Increment) 
Interrupt EI (Enabled) DI (Disabled) 
Sign NG (Negative) PL (Plus) 

Zero ZR NZ 

Auxiliary Carry AC NA 

Parity PE (Even) PO (Odd) 
Carry CY NC 


Whenever you type the RF command, the flags are displayed (in the order 
shown in the previous table) in a row at the beginning of a line. At the end of 
the list of flags, debug displays a hyphen (-). 

You may enter new flag values in any order as alphabetic pairs. You do not 
have to leave spaces between these values. To exit the R command, press the 
RETURN key. Any flags for which you did not specify new values remain 
unchanged. 


If you type more than one value for a flag, debug returns a DF error message. 
If you enter a flag code other than one of those shown in the table above, 
debug returns a BF error message. In both cases, the flags up to the error in the 
list are changed; those flags at and after the error are not. 


When you start debug, the segment registers are set to the bottom of free 
memory, the instruction pointer is set to 0100H, all flags are cleared, and the 
remaining registers are set to zero. 
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Examples: 


If you type the following command, debug displays all registers, flags, and the 
decoded instruction for the current location: 


R 
If the location is CS:11A, for example, the display will look similar to this: 


AX=0E00 BX=00FF CX=0007 DX=01FF SP=039D BP=0000 
SI=005C DI=0000 DS=04BA ES=04BA SS=04BA CS=04BA 
IP=011A NV UP DI NG NZ AC PE NC 

04BA:011A CD21 INT 21 


If you then type the following command, debug will display these flags: 


RF 
NV UP DI NG NZ AC PE NC - _ 


Now, you could type any valid flag designation, in any order, with or without 
spaces. For example, 


NV UP DI NG NZ AC PE NC - PLEICY 


In response, debug would display the debug prompt. To see the changes, type 
either the R or RF command: 


RF NV UP EI PL NZ AC PE CY - _ 


Press the RETURN key to leave the flags this way or to specify different flag 
values. 
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Search 
Purpose: 


Searches the specified range for the specified list of bytes. 
Syntax: 


Srange list 


Comments: 
The list may contain one or more bytes, each separated by a space or comma. If 
the list contains more than one byte, only the first address of the byte string is 


returned. If the list contains only one byte, all addresses of the byte in the range 
are displayed. 


Example: 


Suppose you type the following command: 
SCS:100 110 41 
Debug would display a response similar to 


04BA:0104 
04BA:010D 


-type: 
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Trace 
Purpose: 


Executes one instruction and displays the contents of all registers, flags, and the 
decoded instruction. 


Syntax: 


T[=address] [value] 
Comments: 


If you include the =address option in the T (trace) command, tracing occurs at 
the specified =address. The value option causes debug to execute and trace the 
number of steps specified by value. 


The T command uses the hardware trace mode of the 8086 or 8088 


microprocessor. Consequently, you may also trace instructions stored in ROM 
(Read Only Memory). 


Example: 


Suppose you type the following command: 
T 


In response, debug would return a display of the registers, flags, and decoded 
instruction for that one instruction. Assuming, for this example, that the current 
position is 04BA:011A, debug might return the following display: 


AX=0E00 BX=00FF CX=0007 DX=01FF SP=039D BP=0000 
ST=005C DI=0000 DS=04BA ES=04BA SS=04BA CS=O04BA 
IP=011A NV UP DI NG NZ AC PE NC 

O4BA:011A CD21 INT 21 


If you type the following command, debug executes sixteen (10 hex) 
instructions beginning at 011A in the current segment, and then displays all 
registers and flags for each instruction as it is executed. The display scrolls 
away until the last instruction is executed, and then stops. Now you can see the 
register and flag values for the last few instructions performed: 


T=011A 10 


Remember that if you want to study the registers and flags for any instruction 
(at any time), you can press CONTROLS to stop the display from scrolling. 
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Unassemble 
Purpose: 


Disassembles bytes and displays the source statements that correspond to them, 
with addresses and byte values. 


Syntax: 


U[range] 


Comments: 


The display of disassembled code looks like a listing for an assembled file. If 
you type the U (unassemble) command without parameters, 20 hexadecimal 
bytes are disassembled at the first address after that displayed by the previous 
U command. If you type the U command and include the range parameter, 
debug disassembles all bytes in range. But if you specify range only as an 
address, 20H bytes are disassembled. 


Example: 


Suppose you type the following command: 
U04BA:100 L10 


In response, debug would disassemble 16 bytes, beginning at address 
04BA:0100: 


04BA:0100 206472 AND [SI+72],AH 


O04BA:0103 69 DB 69 

04BA:0104 7665 JBE 016B 
04BA:0106 207370 AND [BP+DI+70],DH 
04BA:0109 65 DB 65 

04BA:010A 63 DB 63 

04BA:010B 69 DB 69 

O4BA:010C 66 DB 66 

O4BA:010D 69 DB 69 

O4BA:010E 63 DB 63 


O4BA:010F 61 DB 61 
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Now, suppose you type the following: 


U04ba:0100 0108 


The display would now show 

04BA:0100 206472 AND 
04BA:0103 69 DB 
04BA:0104 7665 JBE 
04BA:0106 207370 AND 


[SI+72] ,AH 

69 

016B 
[BP+DI+70],DH 


If the bytes in some addresses are altered, the disassembler alters the instruction 
statements. You can then type the U command for the changed locations, for 
the new instructions viewed, and for the disassembled code used to edit the 


source file. 
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Write 


Purpose: 


Writes the file being debugged to a disk file. 
Syntax: 


W|[address (drive: record record\] 
Comments: 


If you do not use parameters with the W (write) command, BX:CX must 
already be set to the number of bytes to be written; the file is written beginning 
from CS:100. If you type the W command with just an address, the file is 
written beginning at that address. If you have used a G (go) or T (trace) 
command, you must reset BX:CX before using the W command without 
parameters. 

Note that if a file is loaded and modified, the name, length, and starting address 
are all set correctly to save the modified file (as long as the length has not 
changed). 

You must have named the file either with the initial debug startup command or 
with the N (name) command (refer to the N command earlier in this manual). 
Both the debug startup command and the N command properly format a 
filename in the normal format of a file control block at CS:5C. 


If you include parameters when you use the W command, the write begins from 
the memory address specified; the file is written to the specified drive: (the 
drive name is numeric: 0=A:, 1=B:, 2=C:, etc.). Debug writes the file 
beginning at the logical record number specified by the first record. Debug 
then continues to write the file until the number of sectors specified in the 
second record have been written. 


Warning Writing to absolute sectors is extremely risky because the process 
bypasses the file handler. 


Examples: 


If you type the following command, debug writes out the contents of memory 
to the disk in drive B, beginning with the address CS:100. The data written out 
starts in the disk logical record number 37H and consists of 2BH records. 


WCS:100 1 37 2B 


When the write is complete, debug displays its prompt again. 
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Debug Error Messages 


During a debug session, you may receive any of the following error messages. 
Each error ends the debug command under which it occurred, but does not end 
debug itself. 


Error 

code Definition 

BF Bad flag 
You attempted to change a flag, but the characters you typed 
were not one of the acceptable pairs of flag values. See the R 
(register) command for the list of acceptable flag entries. 

BP Too many breakpoints 
You specified more than ten breakpoints as parameters to the G 
(go) command. Retype the G command using ten or fewer 
breakpoints. 

BR Bad register 


While using the R command you typed an invalid register name. 
See the R command for the list of valid register names. 

DF Double flag 
You typed two values for one flag. You may specify a flag value 
only once per RF command. 


Appendix A 
Instructions for Users with Single 
Floppy Disk Drive Systems 


If you have only one floppy disk drive, you can still type MS-DOS commands 
just as if you had two disk drives on your system. 


Just think of your one-drive system as having two drives (drive A and drive B). 
But instead of A and B representing two physical drives, they represent disks. 


Just remember that when you specify drive B, when the drive A disk was used 
last, MS-DOS prompts you to insert the disk for drive B. For example, 


A> copy command.com b: 

Insert diskette for drive B: 

and strike any key when ready 
1 File(s) copied 

A>_ 


If you specify drive A when the drive B disk was used last, MS-DOS asks you 
to change disks again, this time prompting you to insert the drive A disk. 


When using a batch file to execute commands, you follow the same procedure. 
MS-DOS waits for you to insert the appropriate disk and press any key before it 
continues. 


Important The letter displayed in the system prompt represents the default 
drive where MS-DOS looks to find a file whose name is entered without a drive 
name; this letter does not represent the last disk used. 


Assume, for example, that A is the default drive. If the last command 
performed was dir b:; MS-DOS would act as if the drive B disk is still in the 
drive. The system prompt, however, is still A>, because A is still the default 
drive. If you type the dir command, MS-DOS prompts you for the drive A 
disk, because it is the default drive and you did not specify another drive in the 
dir command. 
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What is a Configuration File? 


The configuration file config.sys is a file that contains certain commands that 
MS-DOS checks when you start up your computer. Each time you start MS- 
DOS, it searches the root directory of the drive in which it was started for a file 
named config.sys. 

The config.sys file lets you change your system’s default configuration settings. 
For example, you can add installable device drivers to your system by 
including special commands in your config.sys file. 

You can use the dir command to see if the config.sys file is already on your 
disk. If it is on the disk, you can use the type command to display it. For more 
information about the dir and type commands, see Chapter 3, "MS-DOS 
Commands." 


If config.sys already exists, you may want to include other commands in the 
file. For example, you may want to configure for a new device, such as a mouse 
or an external drive. 

If your MS-DOS disk does not have a config.sys file, you can use the MS-DOS 
line editor, Edlin, to create one and then save it on the MS-DOS disk in your 
root directory. If config.sys already exists and you want to change it, you can 
use Edlin to edit it. 
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Config.sys Commands 


The following table briefly describes the purpose of each configuration 


command: 


Command 
break 
buffers 
country 
device 
drivparm 
fcbs 

files 


lastdrive 
shell 


stacks 


Purpose 

Sets CoNTROL-c check. 

Sets the number of sector buffers. 

Allows for international time, date, and currency. 

Installs the device driver in the system. 

Defines parameters for block devices. 

Specifies the number of FCBs that can be open concurrently. 


Sets the number of open files that can access certain MS-DOS 
system calls. 


Sets the maximum number of drives you may access. 


Begins execution of the shell from a specific file (usually 
command.com). 


Supports the dynamic use of data stacks. 


Sample Config.sys File 


A typical configuration file might look like this: 


buffers=30 
device=c: \dev\network.sys 


break=on 


shell=c:\bin\command.com c:\bin /p 
lastdrive=z 
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The following explains how this sample config.sys file configures the system: 


Command 
buffers 
device 


break 


shell 


lastdrive 


Purpose 
Sets the number of buffers in memory to 30. 


Sets a searchpath of c.\dev\network.sys to find the device driver 
being added to the system. In this case, it is network software. 
Generally, you will receive a disk with some installation 
software when you purchase a new device. Make sure that the 
device driver is in the directory that you specify in the device 
command. 

Makes it possible to use conTROL-c in real mode to stop a 
program, depending on the program that you are running. 

Sets the MS-DOS command processor to the command.com file 
located in the bin directory on the disk in drive C. 

a:\bin tells the command processor where to look for 
command.com if it needs to reread the disk. 

The /p switch is used by the command.com shell. For more 


information about command.com and its switches, see Chapter 
3, "MS-DOS Commands." 


Sets the last available label for a logical or physical drive to z. In 
other words, on this computer, letters from a to z are available as 
labels for logical or physical disk drives. 


The following pages describe each configuration command in detail. 
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Break 


Purpose: 


Sets contRoL-c check. 


Syntax: 


break=on 
or 
break=off 


Default: 


break=on 


Comments: 


Depending on the program you are running, you may use CONTROL-C to stop an 
activity (for example, to stop sorting a file). Normally, MS-DOS checks to see 
whether you have pressed controL-c only while it is reading from the keyboard 
or writing to the screen or printer. Therefore, setting break to on extends 
CONTROL-C Checking to other functions, such as disk reading and writing. 


Example: 


To tum off contro-c checking, put the following line in your config.sys file: 
checking 


break=off 
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Buffers 


Purpose: 


Allows you to set the number of disk buffers that MS-DOS allocates in 
memory at the time you start the system. 


Syntax: 
buffers=x 


where: 
x is the number of disk buffers, from 2 to 255. 


Default: 

Configuration Buffers 
For a base system 2 

Any disk over 360K bytes 3 

128K to 255K bytes RAM 5 

256K to 511K bytes RAM 10 
512K bytes or more RAM 15 
Comments: 


A disk buffer is a block of memory that MS-DOS uses to hold data when 
reading or writing. 


For applications such as word processors, a number between 10 and 20 
provides the best performance. If you plan to create a lot of subdirectories, you 
may even want to increase the buffers value to between 20 and 30. Remember, 
though, that buffers take up 512 bytes of space, so the more buffers you have, 
the less memory you will have available for applications. 


Note Feel free to experiment with different buffer settings to see how 
different values affect the way your personal computer operates. 


Example: 


To creat: 20 disk buffers, put the following line in your config.sys file: 


buffers=20 
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Country 
Purpose: 


Country allows MS-DOS to use international time, date, currency, and case 
conversions. 


Syntax: 


country=xa[,Lyyy]{,[drive: |filename]] 
where: 


xxx is the phone country code. 
yyy is the code page for the country. 
filename is a file containing country information. 


Default: 


Unless otherwise specified, United States settings are assumed. 
If you do not specify filename, MS-DOS uses the country.sys file for country- 


specific information. 
Comments: 


This configuration command identifies to MS-DOS which country’s character 
set you intend to use. 


For a list of valid country codes, see Appendix E, "How to Use Code Pages." 


Example: 


The following example sets country to France (=033) and converts 
international currency, time, date, and case to French conventions: 


country=033 
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Device 


Purpose: 


Installs the specified device driver on the system list. 
Syntax: 


device=[drive:][path]filename[argument] 
where: 
argument includes any switches accepted by filename. 


Default: 


None 


Comments: 


The standard installable device drivers provided with MS-DOS are ansi.sys, 
display.sys, driver.sys, printer.sys, and ramdrive.sys. For more information on 
these installable device drivers, see Appendix C, "Installable Device Drivers." 


If you purchase a new device, like a mouse or a scanner, you generally will 
receive device driver software with that device. These installable device drivers 
can be installed using the device command. Once you have installed a device 
driver, make sure that the device driver is in the directory that you specify in 
any device commands. 


Note The device drivers country.sys and keyboard.sys are loaded 
automatically by MS-DOS. Do not try to load either of these with the device 
command. If you do, it will "hang" your system (that is, MS-DOS will not 
Start). 


Example: 


If you plan to use the ANnsI escape sequences described in Appendix C, 
"Installable Device Drivers," you should create a config.sys file that contains 
the following command: 


device=ansi.sys 


This command causes MS-DOS to replace all keyboard input and screen output 
support with the ansı escape sequences. 
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Drivparm 
Purpose: 


This command allows you to define parameters for block devices when you 
start MS-DOS, overriding the original MS-DOS device driver settings. 


Syntax: 


drivparm=/d:number [/c][/f:factor] [/h:heads] [/n][/s:sectors] [/t:tracks] 
Default: 


None 


Comments: 


Setting drivparm overrides any previous block device driver definitions. 
The following list describes how each switch is used: 


Switch Function 


/d:number Physical drive number, ranging from 0 to 255. This means that 
drive number 0=A, 1=B, 2=C, etc. 


Ie Shows that change-line (doorlock) support is required. This 
means that the device driver will be able to tell whether the door 
of a floppy disk drive is open or closed. If the door is open, the 
device driver will assume that the drive does not have a disk in it 
yet. 


/f:factor Specifies the device type (form factor). The default value is 2. 
factor=form factor index, where 


0 = 160/180K bytes, or 

0 = 320/360K bytes 

1 = 1.2 megabytes 

2 = 720K bytes (3.5-inch disk) 

3 = 8-inch single density 

4 = 8-inch double density 

5 = Hard disk 

6 = Tape drive 

7 = 1.44 megabytes (3.5-inch disk) 
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The default values for the following switches depend upon the form factor 
specified with the /f: switch. If you do not specify the /f: switch, drivparm uses 
a default of 720K bytes (3.5-inch disk). 


Switch Function 

{h: heads Maximum head number, ranging from 1 to 99. The default value 
is 2. 

/n Specifies a nonremovable block device. 


/s:sectors Number of sectors per track, ranging from 1 to 99. The default 
value is 9. 


/t:tracks Number of tracks per side on the block device, ranging from 1 to 
999. 


Example: 


Suppose your computer has an internal tape drive on drive D that is configured 
at startup to write 20 tracks of 40 sectors per track. If you want to reconfigure 
this tape drive to write 10 tracks of 99 sectors each, you can put the following 
line in your config.sys file: 


drivparm=/d:3 /f£:6 /h:1 /s:99 /t:10 


This command line overrides the default device driver settings, and supports a 
tape drive as drive D (in this case the logical and physical drive numbers are 
identical). This tape drive has 1 head and supports a tape format of 10 tracks 
and 99 sectors per track. (This assumes that the device driver for the tape 
device supports this configuration of tracks and sectors.) So to create a tape that 
you can read on another computer, one which can read only this alternate 
format, you might want to use this method. 
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FCBS 


Purpose: 


Allows you to determine the number of File Control Blocks (FCBs) that can be 
open concurrently. 


Syntax: 


febs=x,y 
where: 


x is the number of files that File Control Blocks can open at one time. 
y is the number of files opened by FCBs that MS-DOS cannot close 
automatically. 


Default: 


fcbs=4,0 


Comments: 


A file control block is a data structure in real mode used to control open files. 


The allowed values for x range from 1 to 255. The allowed values for y also 
range from 1 to 255. If an application tries to open more than x files by FCBs, 
then all but the first y files may be closed by MS-DOS. 


Note The preferred method of accessing files is to use file handles instead of 
file control blocks. However, some older applications that you want to use may 
require you to use the febs command in your config.sys file. Thus, you should 
only use the febs command if an application requires you to do so. 


Example: 


To open up to four files by FCBs and to protect the first two files from being 
closed, put the following line in your config.sys file: 


fcbs=4,2 
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Files 
Purpose: 


Sets the number of open files that the MS-DOS system calls can access. 


Syntax: 


files=x 
where: 
x is the number of open files that the system calls can access. 


Default: 


files=8 


Comments: 


The vaild values for x range from 8 to 255. The maximum number of files that 
one program can have open at a time is 65,534. 


Note A process must issue MS-DOS system call 67H to activate the extended 
handle. 


Example: 


To let MS-DOS open 20 files at one time, put the following line in your 
config.sys file: 


files=20 
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Lastdrive 
Purpose 


Sets the maximum number of drives you may access. 


Syntax: 


lastdrive=x 
where: 


x can be any letter from A to Z. 


Default: 


lastdrive=e 


Comments 


The x value represents the last valid drive that MS-DOS will accept. The 
minimum number is equal to the number of drives you have installed on your 
computer. 

This command is useful only in a network environment. At start-up, MS-DOS 
recognizes five drives you have on your system. To make any extra drives 
defined by lastdrive valid, a network redirection must occur. 

Note that MS-DOS allocates a data structure for each drive that you specify, so 
you shouldn’t specify more drives than are necessary. 


Example: 


The following command sets the last drive to M, unless you have added an 
external logical device with driver.sys. For information about driver.sys, see 
Appendix C, Installable Device Drivers. 


lastdrive=m 
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Shell 


Purpose: 


Begins execution of the shell (top-level command processor) from a file 
defined by the specified pathname. 


Syntax: 


shell=[drive:][path] filename 
where: 


filename is a command processor program. 
Default: 


The default command processor for MS-DOS is command.com. 
Comments: 


Instead of reading the standard command.com, MS-DOS starts the processor 
specified in filename. 
System programmers who write their own command processors (instead of 


using the MS-DOS file, command.com) should use the shell command to 
specify the name of their shell program. 


MS-DOS sets the COMSPEC environment variable equal to the drive:, path 
and filename specified on the shell command line. This setting overrides the 
default value for COMSPEC (the drive and pathname of the command 
processor initially used to start MS-DOS ). The operating system uses the 
COMSPEC environment setting to determine which file to use when reloading 
any transierit part of the command processor. 


Note The shell command does not accept switches. However, if the new 
command processor does accept switches, you can include those switches in 
this syntax. For example, suppose shell=newcmdp.com. And suppose 
newcmadp.com accepts the /c, /p, /e switches. You can include any of these 
switches in the shell command line. Thus, the following would be a valid 
command: 


shell=newcmdp.com /p 


Example: 


The following command uses the file \bin\newshell as the command processor: 


shell=\bin\newshell 
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Stacks 
Purpose: 


Supports the dynamic use of data stacks. 


Syntax: 


stacks=n,s 
where: 


nis the number of stacks 
s is the size of each stack 


Default: 

Computer Stacks 
For IBM-PC, IBM-XT 0,0 
IBM PC-Portable 

For Other computers 9,128 
Comments: 


The valid values for n range from 0 to 64. The valid values for s range from 0 
to 512. 


When there is a hardware interrupt, MS-DOS allocates one stack from n stack 
specified. When stacks=0,0, MS-DOS will not switch stacks at interrupt time. 


Examples: 


If you want to allocate eight stacks of 512 bytes each for hardware interrupt 
handling, you would include the following command in your config.sys file: 


stacks=8,512 
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Introduction 


Device drivers are programs that let the operating system recognize devices 
that are not part of the computer. Examples of devices are a modem, a printer, a 
mouse and an external disk drive. Some device drivers are already installed 
with MS-DOS. Other device drivers, called installable device drivers, come 
with MS-DOS for you to install if you need them. 


This appendix describes the installable device drivers provided with MS-DOS: 


e — Ansi.sys loads the ansi character set. 

èe Display.sys supports code page switching on the console device. 

e Driver.sys supports external floppy disk drives. 

e Printer.sys provides code page support for PRN, LPT 1, LPT2, and LPT3. 
e Ramdrive.sys supports one or more RAM (virtual) drives. 

For more information about the device configuration command, which is used 


to install these device drivers, see Appendix B, "How to Configure Your 
System.” 


C.2 MS-DOS User's Reference 


Ansi.sys 


The ansi.sys installable device driver lets you use ANsI escape sequences in real 
mode. An ANSI escape Sequence is a series of characters (beginning with an 
escape character or keystroke) developed by the American National Standards 
Institute (ansı). These sequences are used to define functions for MS-DOS. 
Specifically, you can change graphics functions and affect the movement of the 
cursor. 


To install ansi.sys, include a command line of the following form in your 
config sys file: 


device=[drive][path]ansi.sys 


The escape sequences used in the ansi.sys file are listed in an appendix found at 
the end of this manual. 


ANSI Escape Sequences Used with MS-DOS 


This section lists and explains valid ans escape sequences for MS-DOS. 
The variables listed in the escape sequences themselves are as follows: 


Code Description 


Pn Numeric parameter—a decimal number that you specify with ascu 
digits. 
Ps Selective parameter—a decimal number that you use to select a 


subfunction. You may specify more than one subfunction by 
separating the parameters with semicolons. 


PI Line parameter —a decimal number that you specify with ascu digits. 


Pc Column parameter—a decimal number that you specify with asc 
digits. 


Sequence 
ESC [ PI; Pc H 
ESC [ Pl; Pc F 


ESC [ Pn A 


ESC [ Pn B 


ESC [ PnC 


ESC [ Pn D 


ESC[ó6n 


ESC [s 


ESC [ u 
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Function 

Cursor Position (CUP) 

Horizontal & Vertical Position (HVP) 

CUP and HVP move the cursor to the position 
specified by the parameters. When no parameters are 


provided, the cursor moves to the home position (the 
upper-left comer of the screen). 


Cursor Up (CUU) 

This sequence moves the cursor up Pn lines without 
changing columns. If the cursor is already on the top 
line, MS-DOS ignores the CUU sequence. 

Cursor Down (CUD) 


This sequence moves the cursor down Pn lines without 
changing columns. If the cursor is already on the 
bottom line, MS-DOS ignores the CUD sequence. 
Cursor Forward (CUF) 

The CUF sequence moves the cursor forward Pn 
columns without changing lines. If the cursor is 
already in the far right column, MS-DOS ignores the 
CUF sequence. 

Cursor Backward (CUB) 


This escape sequence moves the cursor back Pn 
columns without changing lines. If the cursor is 
already in the far left column, MS-DOS ignores the 
CUB sequence. 


Device Status Report (DSR) 


The console driver outputs an RCP sequence when it 
receives the DSR escape sequence. 


Save Cursor Position (SCP) 

The console driver saves the current cursor position. 
This position can be restored with the RCP sequence. 
Restore Cursor Position (RCP) 

This sequence restores the cursor position to the value 
it had when the console driver received the SCP 
sequence. 
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ESC [2J Erase Display (ED) 


The ED sequence erases the screen. The cursor then 
goes to the home position. 


ESC [K Erase Line (EL) 


This sequence erases from the cursor to the end of the 
line (including the cursor position). 


ESC [ Ps; ...; Ps m Set Graphics Rendition (SGR) 


The SGR escape sequence calls the graphic functions 
specified by the following numeric parameters. These 
functions remain until the next occurrence of an SGR 
escape sequence. 


Graphics Functions 


O All attributes off 

1 Boldon 

2 Faint on 

3 Italic on 

5 Blink on 

6 Rapid blink on 

7 Reverse video on 

8 Concealed on 

30 Black foreground 

31 Red foreground 

32 Green foreground 

33 Yellow foreground 
34 Blue foreground 

35 Magenta foreground 
36 Cyan foreground 

37 White foreground 
40 Black background 
41 Red background 

42 Green background 
43 Yellow background 
44 Blue background 

45 Magenta background 
46 Cyan background 

47 White background 
48 Subscript background 
49 Superscript background 


Parameters 30 through 47 meet the ISO 6429 standard. 


Sequence 
ESC = Ps h 
ESC =h 
ESC =0h 
ESC? 7h 


ESC = Ps 1 
ESC =1 

ESC =01 
ESC ?71 
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Function 

Set Mode (SM) 

The SM escape sequence changes the screen 
width or type to one of the following 
numeric parameters: 


Screen width parameters 


0 40x25 B&W 

1 40x25 color 

2 80x25 B&W 

3 80x25 color 

4 320x200 color 

5 320x200 B&W 

6 640x200 B&W 

7 Wraps at the end of each line 


Reset Mode (RM) 


Parameters for RM are the same as for SM (Set 
Mode), except parameter 7 resets the mode that 
causes wrapping at the end of each line. 
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Display.sys 


Display.sys is an installable device driver that supports code page switching for 
the console device. 


To install display.sys, insert a command line of the following form in your 


config.sys file: 


device=[drive:][path]display.sys con(:]=[type[,hwcp][,n,m]] 


The following list describes how each variable is used: 


Option 
type 


hwcp 


Function 


The display adapter in use. Valid values include MONO, CGA, 
EGA, and LCD. 


The code page supported by the hardware. The following values 
are allowed: 


437 (United States) 

850 (Multilingual) 

860 (Portugal) 

863 (French-Canadian) 

865 (Norway) 

The number of additional code pages that can be supported. This 
number is dependent on the hardware. MONO and CGA do not 
support other fonts, so n must be 0. EGA can be 2. LCD can be 
1. 


The number of sub-fonts that are supported for each code page. 
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Driver.sys 


Driver.sys is an installable device driver that supports external floppy disk 


drives. 


To install driver.sys, insert a command line of the following form in your 


config.sys file: 


device=driver.sys /d:number [/c] [/f.factor] [/h:heads] [/n] {/s:sectors] 


[/t:tracks] 


The driver.sys device driver accepts the following switches: 


Switch 
/d:number 


le 


/f:factor 


Function 


Physical drive number, ranging from 0 to 255. The first physical 
floppy disk drive is number 0, and is referenced from the MS- 
DOS command line as drive A. Drive number 1 is the second 
physical floppy disk drive. Drive 2 is the third, which must be 
external. 


Shows that change-line (doorlock) support is required. This 
means that the device driver will be able to tell whether the door 
of a floppy disk drive is open or closed. If the door is open, the 
device driver will assume that the drive does not have a disk in it 
yet. 


Specifies the device type (form factor). The default value is 2. 
factor=form factor index, where 


0 = 160/180K bytes, or 

0 = 320/360K bytes 

1 = 1.2 megabytes 

2 = 720K bytes (3.5-inch disk) 

3 = 8-inch single density 

4 = 8-inch double density 

5 = Hard disk 

6 = Tape drive 

7 = 1.44 megabytes (3.5-inch disk) 
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/h:heads Maximum head number, ranging from 1 to 99. The default value 
is 2. 

m Specifies a nonremovable block device. A fixed disk is an 
example of a nonremovable block device. 


/s:sectors Number of sectors per track, ranging from 1 to 99. The default 
value is 9. 


/t:tracks Number of tracks per side on the block device, ranging from 1 to 
999. The default value is 80. 
Examples: 


To add an external 720K-byte drive to your computer, you would include the 
following line in the config.sys file: 


device=driver.sys /d:02 
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Printer.sys 


Printer.sys is an installable device driver that supports code page switching for 
parallel ports LPT1, LPT2, and LPT3. (The port name PRN may be substituted 
for LPT1 to refer to the first parallel port.) 


To install printer.sys, insert a command line of the following form in your 


config.sys file: 


device=[drive:][path]printer.sys Iptx= [type[,hwcp[,...]][,”]] 


The printer.sys device driver accepts the following options: 


Option 


type 
hwcp 


Function 
The printer in use. 


The code page supported by the hardware. The following values 
are allowed: 


437 (United States) 
850 (Multilingual) 

860 (Portugal) 

863 (French-Canadian) 
865 (Norway) 


The number of additional code pages that can be supported. This 
number is dependent on the hardware. 
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Ramdrive.sys 


Ramadrive.sys is an installable device driver that lets you use a portion of your 
computer’s memory as if it were a hard disk. This memory area is called a 
RAM disk and is sometimes referred to as a virtual disk. 

RAM disks are much faster than hard disks because the information they 
contain is always loaded into memory. If your computer has extended memory 
installed (starting at the one megabyte boundary), or if you have an extended 
memory board that meets the Lotus/Intel/Microsoft Expanded Memory 
Specification, you can use this extended memory for one or more RAM disks. 
Otherwise, ramdrive.sys places RAM disks in low memory. 


Note The command device=ramdrive.sys increases the size of MS-DOS 
resident in memory. 


To install ramdrive.sys, include a command line of the following form in your 
config.sys file: 

device=ramdrive.sys [disksize] [sectorsize] [entries] [/e] 

or 

device=ramdrive.sys [disksize] [sectorsize] [entries] [/a] 


The ramdrive.sys device driver accepts the following options: 


Option Function 

disksize Specifies the disk size in kilobytes. The default size is 64K 
bytes; the minimum size, 16. 

sectorsize Specifies the sector size in bytes. The default size is 128 bytes. 
The following values are allowed: 128, 256, 512, and 1024 
bytes. 

entries Specifies the number of root directory entries. The default value 
is 64; the minimum, 4; the maximum, 1024. 
Ramdrive.sys adjusts the value of entries to the nearest sector 
boundary. For example, if you specify a value of 25 when the 
sector size is 512 bytes, the 25 will be rounded up to 32, which 
is the next multiple of 16 (there are sixteen 32-byte directory 
entries in 512 bytes). 
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le Lets you use extended memory (above one megabyte) as a RAM 
disk if it has been installed. If you use this switch, you cannot 
use the /a switch. It is recommended that you use the /e switch. 

/a Lets you use an extended memory board that meets the 
Lotus/Intel/Microsoft Expanded Memory Specification for a 
RAM drive—if that board has been installed. If you use this 
switch, you cannot use the /e switch. 


Note When you reset or turn off the power on your computer, the information 
stored in RAM disks is lost. 


Appendix D 
Configuring Your Hard Disk 
(Fdisk) 


Introduction 


Hard disks can be divided into one to four separate sections, called partitions. 
Partitions separate your hard disk into individual areas, and each partition may 
contain a different operating system. 


To prepare your hard disk for the MS-DOS operating system, you must create a 
partition for MS-DOS, called a DOS partition. You can create a DOS partition 
on your hard disk by using a menu-driven utility called fdisk. You must use 
fdisk if you want to do one of the following: 


e Create a primary MS-DOS partition 
e Create an extended DOS partition 

e Change the active partition 

e Delete a DOS partition 

e Display partition information 


e Review or modify the configuration of another hard disk on your 
computer 


Warning Reconfiguring your disk with fdisk destroys all existing files. Be 
sure to have a backup of all files on your disk before you create an MS-DOS 
partition with fdisk. 
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Checking for a Configured and Formatted 
Disk 


Many computer stores configure hard disk computers for MS-DOS, so you may 
not need to use fdisk. They may also format your hard disk to start MS-DOS 
when you turn the power on. To find out whether this has been done, do the 
following: 
1. First, try to to start MS-DOS from your hard disk. 
e If it starts, your hard disk is both configured and formatted, and the 
MS-DOS system files are on the disk. 
e If MS-DOS does not start, your disk is not formatted to start MS- 
DOS, but may have been configured. 


2. If MS-DOS did not start, check to see if the disk has been configured with 
fdisk. Place the MS-DOS master floppy disk in drive A and press CONTROL- 
ALT-DELETE to start MS-DOS. Then run fdisk and select the "Display 
Partition Data" to see if any MS-DOS partitions exist. 


e If any do exist, your disk has been configured. 


e _ If no partitions exist, follow the instructions in this appendix to 
configure your disk. 


3. After your hard disk is configured, be sure to format your disk with the 
MS-DOS format /s command before you copy files onto the disk. 
Otherwise, your files will be unreadable. 


How to Start Fdisk 


The fdisk utility is easy to use because it uses menus to lead you through each 
procedure. To start fdisk, follow these steps: 

1. Place the MS-DOS disk in drive A. 

2. Tum on your computer to start MS-DOS. 

3. Type the following command and press the RETURN key: 


Fdisk 


In response, fdisk displays its main menu on your screen. This menu lists five 
choices. If your computer has only one hard disk, Choice 5 will not appear on 
your screen. 
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Disk Options 
Current Fixed Disk Drive: 1 
Choose one of the following: 


1. Create DOS Partition 

2. Change Active Partition 

3. Delete DOS Partition 

4. Display Partition Data 

5. Select Next Fixed Disk Drive 
Enter choice: [1] 


Press ESC to return to DOS 


The following sections describe each of these options, and show the menus and 
other information they display. To return to MS-DOS from the main menu, just 
press the esc key. You can also use the Esc key to return to the main menu from 
any of the fdisk menus. 

Most of the fdisk menus displays a default value. To choose the default value, 
press the RETURN key. To choose another value, just type the value you want, 
and press the RETURN key. 


How to Create a DOS Partition 


If you choose the first option on the main menu, and if your hard disk is not yet 
completely partitioned, fdisk displays a screen like the following. If no 
extended partitions exist, the third option is not displayed: 

Create DOS Partition 

Current Fixed Disk Drive: 1 


1. Create Primary DOS Partition 
2. Create Extended DOS Partition 
3. Create Logical DOS Drive(s) in the Extended DOS 
Partition 
Enter choice: [1] 


Press ESC to return to Fdisk Options 
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Selection 1: Create Primary DOS Partition 


You must create a primary MS-DOS partition first before you can create any 
extended MS-DOS partitions on your disk. In most cases, you will need only 
one MS-DOS partition for your entire disk. 


To create a primary MS-DOS partition, press the RETURN key to accept the 
default selection (1). 


The Create Primary DOS Partition menu appears next: 


Create Primary DOS Partition 
Current Fixed Disk Drive: 1 


Do you wish to use the maximum size 
for a DOS partition and make the DOS 
partition active (Y/N)......... ? [Y] 


Press ESC to return to Fdisk Options 


If you use your entire hard disk for MS-DOS, you will use the fdisk program 
only once to create the pnmary MS-DOS partition. If you want to use the entire 
hard disk (up to 32 megabytes) for MS-DOS, press the RETURN key to accept the 
default selection (Y). 


Fdisk then displays the following message: 


System will now restart 


Insert DOS diskette in drive A: 
Press any key when ready . 


Put your MS-DOS disk in drive A and press any key to restart MS-DOS. 

Now that you have created your MS-DOS partition, you must format your hard 
disk so that MS-DOS can use it. If you want to start MS-DOS from your hard 
disk, remember to use the /s switch with the format command. For example, if 
you are formatting the disk in drive C and want to start MS-DOS from that 
disk, type the following command: 


format c: /s 


(For more information about the format command, see Chapter 3, "MS-DOS 
Commands.") 


Appendix D Configuring Your Hard Disk (Fdisk) D.5 


Creating More than One MS-DOS Partition 


You may choose to create a primary MS-DOS partition smaller than the 
maximum size. To do this, type N (for No) in response to the question on the 
first Create Primary DOS Partition menu. Fdisk displays a second Create 
Primary DOS Partition menu like the following. From this menu, you can 
specify the size of the primary MS-DOS partition: 


Create Primary DOS Partition 
Current Fixed Disk Drive: 1 
Partition Status Type Start End Size 


Total disk space is 732 cylinders. 
Maximum space available for partition 
is 732 cylinders. 


Enter partition size............ [ 732] 


Press ESC to return to Fdisk Options 


The space available on your hard disk is measured in cylinders, also called 
tracks. This menu shows the total number of cylinders available for a hard disk 
partition, and prompts you to enter the size of your new partition. The default 
size for the partition is the maximum available space on the hard disk. Press the 
RETURN key if you want the default size; otherwise, type the size (in cylinders) 
that you want for the partition, and press the RETURN key. 


Any part of the disk that you do not use for the primary MS-DOS partition may 
be used for an extended MS-DOS partition. 


Selection 2: Create Extended DOS Partition 


You can use fdisk to create an extended partition if your disk is larger than 32- 
megabytes (the maximum partition size), or if you want to designate one or 
more logical drives for the disk. 
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To select Create Extended DOS Partition, type 2, then press the RETURN key. In 
response, fdisk displays a menu like this one: 


Create Extended DOS Partition 


Current Fixed Disk Drive: 1 


Partition Status Type Start End Size 
Ce -1 A PRI DOS 0 599 600 


Total disk space is 1263 cylinders. 
Maximum space available for partition 
is 663 cylinders. 

Enter partition size............ [ 663] 


Press ESC to return to Fdisk Options 


This menu shows the total number of cylinders available for an extended 
partition. The default for the partition size is the maximum available space on 
the hard disk. Press the RETURN key if you want the default; otherwise, type the 
size (in cylinders) that you want for the partition, and press the RETURN key. 


Note If fdisk finds any defective tracks at the start of the partition, it adjusts 
the partition boundaries to avoid those bad tracks. 


Selection 3: Create Logical Drive in the Extended DOS 
Partition 


When you have created an extended partition, you must specify one or more 
drive letters for that area of the disk. After you create an extended partition and 
if you choose option 3 from the Create Dos Partition menu, fdisk displays a 
menu similar to the following: 


Create Logical DOS Drive(s) 


Drv Start End Size 
D: 650 1049 400 


Total partition space is 1000 cylinders. 
Maximum space available for logical 
drive is 600 cylinders. 


Enter logical drive size............ [ 600] 


Press ESC to return to Fdisk Options 
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You may designate the entire partition as one logical drive, or divide it into two 
or more logical drives. For example, if you want to segregate a particular 
application and its data files to their own drive, you may want to create a 
second logical drive on the partition. 

Because you cannot use an MS-DOS extended partition without a drive letter, 
fdisk continues to prompt you for logical disk drive information until the whole 
partition has been assigned to a logical drive. 


When the entire partition is assigned to logical drives, fdisk displays this 
message: 


All available space in the Extended DOS 
partition is assigned to logical drives. 


Press Esc to return to the main fdisk menu. From there, you can restart MS- 
DOS, or select another option. 


How to Change the Active Partition 


If you choose the second option on the main menu, fdisk displays a screen 
showing the status of each partition on your hard disk. The active partition, 
indicated by a status of A, contains the operating system and files you access 
when you turn on or reset your computer. If you have created a partition on 
your disk with another operating system, this menu allows you to make that 
partition the active partition. Only one partition is active at a time; the others 
are not active. 


For example, if you have both XENIX and DOS partitions on your disk, the 
Change Active Partition menu might look like this: 

Change Active Partition 

Current Fixed Disk Drive: 1 

Partition Status Type Start End Size 


C: 1 non DOS 0 1 1 
2 non DOS 2 401 400 
3 A PRI DOS 402 731 330 


Total disk space is 732 cylinders. 


Enter the number of the partition you 
want to make active........ec.eeeceeee- 3] L] 


Press ESC to return to Fdisk Options 
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Type the number of the partition that you want to activate, and press the RETURN 
key. The default setting is the active partition number. 


If your hard disk contains only MS-DOS partitions, fdisk displays the 
following message instead of prompting you for the partition that you want to 
activate: 


The only startup partition on Drive 1 
is already marked active. 


Press ESC to return to FDISK Options. 


How to Delete a DOS Partition 


If you choose the third option on the main menu, fdisk displays the following 
menu, which asks you to identify whether the partition you want to delete is a 
primary or extended DOS partition: 


Delete DOS Partition 
Current Fixed Disk Drive: 1 


1. Delete Primary DOS Partition 

2. Delete Extended DOS Partition 

3. Delete Logical DOS Drive(s) in 
the Extended DOS Partition 


Enter choice: [ ] 
Press ESC to return to Fdisk Options 


Type the number of the selection you want and press the RETURN key. The next 
menu, whether for a primary or extended DOS partition, shows the status of 
that partition. When you delete a DOS partition, fdisk deletes the partition 
boundaries and any data that existed in that partition. Once you delete the 
Partition, you cannot recover the data that was on it. 


Note You cannot use fdisk to delete a non-DOS partition. Instead, to continue 
using MS-DOS after you have deleted the DOS partition, you must put a MS- 
DOS program disk into drive A. To start a different operating system in another 
partition of your hard disk, you must change the active partition to that number 
before you delete the DOS partition. 
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Selection 1: Delete Primary DOS Partition 


The Delete Primary DOS Partition menu will look similar to this: 


Delete Primary DOS Partition 
Current Fixed Disk Drive: 1 


Partition Status Type Start End Size 
C: 1 A PRI DOS 0 399 400 
2 EXT DOS 400 731 332 


Total disk space is 732 cylinders. 


Warning! Data in Primary DOS 
partition will be lost. Do you wish 
to CONEANUC 6 wes sce erir ie eS eee ee ? [N] 


Press ESC to return to Fdisk Options 


If you do not want to delete the primary DOS partition, press the RETURN key to 
accept the default value (N). 


To delete the primary DOS partition, 


1. TypeY. 
2. Press the RETURN key. 


Selection 2: Delete Extended DOS Partition 


If you choose to delete an extended partition, you must first delete the logical 
drives associated with that partition. 
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Selection 3: Delete Logical Drive in the Extended DOS 
Partition 


To delete a logical drive, type 3 to select the option Delete Logical DOS 
Drive(s) in the Extended DOS Partition from the Delete DOS Partition menu. 
Then press the RETURN key. Fdisk displays a menu like the following: 


Delete Logical DOS Drive(s) 


Drv Start End Size 
D: 400 999 600 
E: 1000 1399 400 


Total partition space is 1000 cylinders. 
Warning! Data in the logical DOS drive will be lost. 


What drive do you wish to 
Press ESC to return to Fdisk Options 


Type the letter of the drive you want to delete, and press RETURN. Fdisk displays 
this message: 


Are YOU SULE... cee rece cree rece cence ? [N] 


If this logical drive contains valuable data you have not backed up, press 
RETURN. This stops fdisk from deleting the logical drive. 


Note Be sure to back up all files you will need from the logical drive before 
you delete the drive. When fdisk deletes a logical drive or partition, the data is 
destroyed. 


If you are sure you want to delete the drive, type Y (for Yes). 
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How to Display Partition Data 


If you choose the fourth option on the main menu, fdisk displays a menu that 
contains information about each of the partitions on your hard disk. 


For example, the Display Partition Information menu might look like this: 


Display Partition Information 
Current Fixed Disk Drive: 1 


Partition Status Type Start End Size 
C: 1 A PRI DOS 0 399 400 

2 EXT DOS 400 731 332 
Total disk space is 732 cylinders. 


The Extended DOS partition contains 
logical DOS drives. Do you want to 
display logical drive information? [Y] 


Press ESC to return to Fdisk Options 


This information screen identifies the partitions on your disk. It shows each 
partition’s number, status, and type, its starting and ending cylinder numbers, 
and its size in cylinders. 

If you have an extended partition, fdisk asks if you want to see information 
about that partition’s logical drives. Type Y and press RETURN to display a screen 
like the following: 


Display Logical DOS Drive(s) 


Drv Start End Size 
D: 400 999 600 
E: 1000 1399 400 


Press ESC to return to Fdisk Options 


Press the Esc key to return to the main menu. 
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How to Select the Next Fixed Disk Drive 


This option appears on the fdisk main menu only if you have more than one 
hard disk attached to your computer. If you choose this option, fdisk changes 
the current disk drive to the next drive. 


For example, if the current disk drive is drive C, and if you choose option 5 on 
the main menu, fdisk changes the current disk drive to drive D. You could then 
choose any of the fdisk options (1-4) to prepare the second fixed disk for MS- 
DOS. Or, you could select option 5 once again to select the next drive. For 
example, if there is not a third fixed disk, fdisk changes the current disk drive 
from D back to C. 


After you have selected the next drive, fdisk displays the main menu again. 
Note that near the top of the screen, there is a line that looks something like 
this: 


Current fixed disk drive: 2 


The activity you select will be performed on the disk shown in this line. 


Appendix E 
How to Use Code Pages 


Introduction 


MS-DOS 3.3 provides national language support through the use of language- 
specific code pages. If you live in, or work with, a country other than the 
United States, you may choose to use the MS-DOS commands that support 
code page switching. 

A code page is a table that defines the character set you are using. A character 
set is a country-specific or language-specific group of characters that are 
translated from the code page table and displayed by your screen or printer. 
Each code page character set contains 256 characters. An example of a 
character set is the set of letters, numbers, and symbols (such as accent marks) 
used by French-Canadians. 


MS-DOS 3.3 supports five different code pages: 


e 437 - United States code page. 


e 850 - Multilingual code page. This code page includes all characters for 
most languages of European, North American, and South American 
countries. 

e 860 - Portuguese code page. 

e 863 - French-Canadian code page. 

e 865 - Nordic code page. This code page includes all characters for the 
Norwegian and Danish languages. 


MS-DOS also provides national language support through the use of two other 

codes: 

e A country codes define the country in which you live or work. MS-DOS 
uses this code to prepare and assign default code pages for your system. 
MS-DOS recognizes 19 different country codes. 


e A keyboard code defines the type of keyboard you are using. MS-DOS 
recognizes 17 different keyboard codes. 
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National Language Support Codes 


The following table lists each country (or language) supported by MS-DOS 3.3. 
The table also lists the related country codes, default code page assignments, 
and related keyboard codes. The code pages shown are automatically prepared 
by MS-DOS when you load the corresponding country code through the 
config.sys country command. If you do not specify a country code, MS-DOS 
loads the default United States code page 437. 


Country or Country 
language code 
United States 001 
French-Canadian 002 
Latin America 003 
Netherlands 031 
Belgium 032 
France 033 
Spain 034 
Italy 039 
Switzerland 041 
United Kingdom 044 
Denmark 045 
Sweden 046 
Norway 047 
Germany 049 
English (International) 061 
Portugal 351 
Finland 358 
Arabic countries 785 
Israel 972 
Notes 


Code 

pages 

437,850 
863,850 
437,850 
437,850 
437,850 


437,850 
437,850 
437,850 
437,850 
437,850 


865,850 
437,850 
865,850 
437,850 
437,850 


860,850 
437,850 
437 
437 


Keyboard 
code 


us 
cf 
la 
nl 
be 


fr 

sp 

it 
sfisg 
uk 
dk 
sv 
no 
gr 


po 
su 


e Both Swiss-French and Swiss-German use country code 041. 


e Code pages for Arabic and Hebrew languages are not available. Country 
codes 785 and 972 assume United States code page 437, but include 
country-specific date and time conventions. 
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Commands that Support National 
Languages 


Several MS-DOS commands—new and old—support code page selection and 
national languages. 


New MS-DOS Commands 

MS-DOS 3.3 includes three new commands: 

nisfunc Loads the file containing country-specific information. 

chep Displays or changes the current code page for the system and all 
prepared devices. 

select Installs MS-DOS on a new floppy disk with selected country- 


specific information and keyboard code. 


Enhanced MS-DOS Commands 


In addition to the new commands, MS-DOS 3.3 includes several enhanced MS- 
DOS commands that support code page selection. The most significant 
enhancements include 


keyb Allows you to select a country-specific keyboard code for the 
keyboard you are using, and a code page for the character set 
you prefer. You may also select an alternate keyboard definition 
file (other than the default keyboard.sys file) with this 
command, if another exists. 


mode Includes several new options 
e Preparing a code page for a device 
e Selecting a code page for a device 


e Displaying the code pages prepared and selected for a 
device 


e Refreshing code pages that were lost due to hardware error 
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New and Enhanced Configuration Commands 


Two config.sys commands also support country-specific information: 


country Identifies the country in which you work or live. This command 
also defines country-specific conventions to be used, such as 
date and time formats and sorting sequence for the character set. 


device Installs device drivers in the system, including two MS-DOS 
installable device drivers that support code page switching. 
These device drivers are called 
e Display.sys — used to install a standard console screen 
device with code-page support 
e = Printer .sys — used to install a standard parallel printer with 
code-page support 


Date and Time Formats 


Four other MS-DOS commands—date, backup, specific date restore, and 
time—now use country-specific date and time conventions, based on the code 
pages you choose to use. 

The following table lists the date and time formats related to each country (or 
language group). These formats are determined by the country code set in your 
config.sys file. 

For each country, the Date format column shows how MS-DOS would display 


January 3, 1989, and the Time format column shows how MS-DOS would 
display 5:35 p.m. (with zero seconds and zero hundredths of seconds). 


Country or Country Date Time 
language code format format 
United States 001 1-03-1989 17:35:00.00 
French-Canadian 002 1989-01-03 17:35:00,00 
Latin America 003 03/01/1989 17:35:00.00 
Netherlands 031 03-01-1989 17:35:00,00 
Belgium 032 03/01/1989 17:35:00,00 
France 033 03/01/1989 17:35:00,00 
Spain 034 03/01/1989 17:35:00,00 
Italy 039 03/01/1989 17:35:00,00 
Switzerland 041 03.01.1989 17.35.00.00 
United Kingdom 044 03-01-1989 17:35:00.00 
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Country or Country Date Time 
language code format format 
Denmark 045 03/01/1989 17.35.00,00 
Sweden 046 1989-01-03 17.35.00,00 
Norway 047 03/01/1989 17.35.00,00 
Germany 049 03.01.1989 17.35.00,00 
English 

(International) 061 03-01-1989 17:35:00.00 
Portugal 351 03/01/1989 17:35:00,00 
Finland 358 03.01.1989 17.35.00,00 
Arabic 

countries 785 03/01/1989 17:35:00,00 
Israel 972 03 01 1989 17:35:00.00 


How to Use Code Pages 


Unless you specify otherwise, MS-DOS assumes that you want to use the 
United States character set. To set your system to support another character set, 
you need to do four things: 


e Set the country code in your config.sys file. This code identifies the 
country in which you live or work. 


e Load the country.sys file or other file containing the country-specific 
information for your country. 


e Set the system code page. For most country codes, MS-DOS automatically 
prepares two system code pages and selects the primary code page for 
your country automatically. If you want to use the other code page 
prepared for your country, you can use the chcp command. 


e Set the keyboard code with the keyb command. 


Note Remember that when you change your config.sys file, you must restart 
MS-DOS to enable the new settings. 


Example: 
Suppose you live in Quebec, Canada. You would follow these steps to use 
French-Canadian character set with your system: 
1. First, add the following line to your config.sys file: 
count ry=002 
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2. Then, restart MS-DOS so that MS-DOS will read your revised config.sys 
file. 


3. Next, type the nlsfunc command to load the country-specific information 
found in the country.sys file on your system: 


nisfunc 


Note If you forget to type the nlsfunc command, MS-DOS will not allow you 
to specify code pages or keyboard codes. 


4. MS-DOS will automatically select the French-Canadian code page for you 
to use. Because your country code is 002, MS-DOS has also prepared the 
Multilingual code page for your system. If you would like to change the 
system code page, type 


chep 850 


5. Select the French-Canada keyboard code CF by typing the following 
command: 


keyb cf 


Note In place of steps 3, 4, and 5, you could add the following lines to your 
autoexec.bat file. Then you would not have to type these commands each time 
you started MS-DOS. 


nlsfunc 
chep 850 
keyb cf 


Now your computer is set up to use the French-Canadian character set. Since 
your console screen and printer are independent devices, you will also need to 
set them up for national language support. The next section explains how to do 
this. 


How to Set Device Code Pages 


MS-DOS 3.3 lets you define code pages for screen and parallel printer devices 
that support code pages switching. Unless you want to use the United States 
code page 437, you will want to set up your screen and printer to use the same 
code page as the rest of your system. 


To set up your console screen device (CON) to use code pages, use the 
config.sys device command to load the display.sys device driver. 
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Example: 


For example, suppose you are using an EGA display, and want to use the 
Multilingual code page 850. You could include this command in your 
config.sys file: 


device=display.sys con=(ega, 850, 2) 


The last option, 2, will allow you to prepare up to two code pages for this 
device. This is useful if you want to switch between code pages. 


Note Remember to restart MS-DOS to initiate the changes you have made to 
the config.sys file. 


If you have a parallel printer connected to your personal computer, you will 
want to prepare the same code pages for your printer as for the rest of your 
system. To do this, use the config.sys device command again to load the 
installable device driver called printer.sys. 


Example: 


If you have an IBM Proprinter, model 4201, connected to LPT1, you would 
include the following line in your config.sys file: 


device=printer.sys lptl=(4201,850,2) 


This command line assumes that the printer.sys file is on the same disk as your 
config.sys file. The last variable, 2, will let you prepare up to two code pages 
for this printer. 


Note There is no limit to the number of times you can use the device 
command in your config.sys file. 


How to Switch between Code Pages 


If you work in an environment that works with more than one language, you 
may need to switch between code pages. For example, suppose you work for an 
international company with offices in New York, London, Stockholm, and 
Oslo. You may need to use two or three different code pages to read or work 
from the correspondences you receive from your other offices. 
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To illustrate how to switch code pages for your system and your devices, 
suppose that you want to change to Nordic code page 865 to work with some 
information you receive from the Oslo office. You would follow these steps: 


1. First, be sure you have typed the nlsfunc command. You only need to type 
this command once in order to load the country-specific information from 
the country.sys file. 


2. Prepare the code page for each device you intend to use. For example, you 
would type the following command to prepare code page 865 for the 
parallel printer connected to LPT2: 


mode lpt2 codepage prepare=865 


MS-DOS then displays the following message to let you know the code 
page was prepared for your device: 


MODE Prepare Codepage function completed 


To prepare code page 865 for your console screen device (CON) you 
would type the following command: 


mode con codepage prepare=865 


3. Next, change the code page for the system and all prepared devices by 
typing the following: 


chep 865 


The display on your screen may flicker slightly as MS-DOS loads a new 
code page for that device. 


4. If for some reason you want to load a different code page for a single 
prepared device, you would use the select keyword with the mode 
command. For example, to load code page 850 for your printer, type this 
command: 


mode lpt2 codepage select=850 


MS-DOS then displays the following message to let you know the code 
page was prepared for your device: 


MODE Select Codepage function completed 


Note If you want to use these commands on a regular basis, you can include 
these command lines in your autoexec.bat file. 
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How to List Current Code Pages 


You can list the current prepared and selected code pages for your console 
screen or a parallel printer by using the mode command in the following form: 


mode device codepage 


For example, to display the current code pages for your console screen device, 
type the following: 


mode con codepage 
MS-DOS displays a message similar to this one: 


Active codepage for device CON is 437 
hardware codepages: 
Codepage 850 
prepared codepages: 
Codepage 437 
Codepage 850 
Codepage not prepared 
Codepage not prepared 
MODE Status Codepage function completed 


How to Refresh Lost Code Pages 


It is possible for prepared code pages to be lost due to hardware errors or other 
reasons. For example, if you prepared code pages for your printer, and then 
turned off the printer, the current code page may be lost. You can use the 
refresh keyword with the mode command to restore the lost code page. 


To illustrate, suppose you had selected code page 850 as the active code page 
for your console screen (CON), but because of a hardware error, the active 
code page was lost. You could type the following commands to reinstate the 
active code pages for your screen: 


mode con codepage prepare=((850}) ega.cpi) 
mode con refresh 
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How to Format a Disk 
with Country-Specific Information 


MS-DOS 3.3 includes a special command, select, that will 
e Format a disk. 


e Create a config.sys file and autoexec.bat files with country-specific 
information. 


e Copy the contents of the source disk to the target disk. 


Warning Do not use the select command with a disk that already contains 
data files, unless you have backed up the files. Any data on the disk is 
destroyed when the disk is formatted by either the select command or the 
format command. 


Example 


To illustrate how the select command works, suppose after configuring your 
hard disk with fdisk you wanted to format your hard disk C. You also want to 
include the Latin American code page and keyboard code on your hard disk. 
After placing your MS-DOS master disk in drive A, you could type the 
following: 


select a: c: 003 la 


After formatting the disk in drive C, select creates two files on the target 
disk—autoexec.bat and config.sys. The contents of the autoexec.bat file will 
look something like this: 


path c: 
keyb la 437 
echo off 
cls 

date 

time 

ver 


The contents of the config.sys file will look simular to the following: 
country=003, 437 


Finally, the select command copies the MS-DOS files to the disk on drive D. If 
autoexec.bat and config.sys files exist on drive A, select does not copy them to 
drive C. 


Appendix F 
MS-DOS Message Directory 


MS-DOS Messages 


There are three types of messages that you could see on your screen: 


e MS-DOS utility messages 

e MS-DOS device error messages 

e Application program messages 

MS-DOS utility and device error messages are listed in this appendix. For 


instructions about error messages related to non-MS-DOS software, see your 
application’s documentation. 


If a disk or device error occurs at any time during a command or program, MS- 
DOS displays an error message, and includes this prompt: 

Abort, Ignore, Retry, Fail? _ 

MS-DOS waits for you to type one of the following responses: 


A Abort. End the program requesting the disk read or write. 
I Ignore. Ignore the bad sector and pretend the error did not occur. This 
may result in lost data. 


R Retry. Repeat the operation. You should use this response when you 
have corrected the error (for example, with Not ready or Write 
protect errors). 
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F Fail. This causes the current MS-DOS system operation to end (fail) 
and the application to continue. 


Note For some floppy disk device errors, the "Ignore" option will not be 
displayed. This prompt instead will read 


Abort, Retry, Fail? 


Usually, you will want to recover by first typing R (to try again). If the second 
attempt fails, type A to terminate the process. 


This section describes MS-DOS messages, their causes, and how to correct 
them. It identifies the list of sources in brackets ([ ]) for each message. 


Abort edit (Y/N)? A 

[Edlin] 

e MS-DOS displays this message when you choose the Edlin Q (quit) 
command. The Q command exits the editing session without saving any 
editing changes. 

Type Y (for Yes) or N (for No). 


Access denied 
[Attrib] [Find][Print][Replace][Xcopy] 
e You tried to replace a write-protected, read-only, or locked file. 


Active Code Page: xxx 
[Chep] 
èe xx is the code page currently being used by the system. 


Active Code Page for device ddd is xxx 
[Mode] 
e xxx Is the code page currently being used by the device ddd. 


Active Code Page not available from con device 

[Keyb] 

© The code page that the system is currently using is not supported on the 
console (screen) you are using. 


Add filename? (Y/N) 

[Replace] 

e Replace displays this prompt if you specify the [|w switch. 
Type Y (for Yes) if you want to add the file to the disk, or N (for No) if 
you do not want to add the file. 
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Adding filename 

[Replace] 

e Replace displays this prompt to let you know that it is adding this file to 
your disk. 


All files canceled by operator 


[Print] 
e MS-DOS displays this message when you specify the ht switch with the 
Print command. 


All logical drives deleted in the Extended DOS Partition 

[Fdisk] 

e Any logical drives previously associated with the extended DOS partition 
on your disk are now removed. 


Allocation error, size adjusted 

[Chkdsk] 

e = The size of the file indicated in the directory was not consistent with the 
amount of data actually allocated to the file. The file was truncated to 
match the amount of data allocated. 


All specified file(s) are contiguous 
[Chkdsk] 
e = All files are written sequentially on the disk. 
To correct this error automatically, specify the chkdsk /f switch. 


APPEND already installed 

[Append] 

e You have already used the Append command once since you turned on 
your computer. Now you are trying to use either the /x or /e switch with 
this command. These switches are only valid the first time you type the 
Append command. 

If you want to change the append switch, reboot your computer. Then 
type the append command with the switch you want to use. Otherwise, 
use the append command without these switches. For more information 
about the append command, see Chapter 3, "MS-DOS Commands." 


APPEND/ASSIGN Conflict 

[Append] 

e You cannot use the Append command on an assigned drive. 
Cancel the drive assignment before using the append command with this 
drive again. 
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Are you sure (Y,N)? 

[MS-DOS] 

e MS-DOS displays this message if you try to delete all files in the working 
directory by using the *.* wildcard. 
Type Y (for Yes) to delete all the files, or N (for No). 


Attempted write-protect violation 
[Format] 
e The disk you are trying to format is write-protected. 


***Backing up files to drive x:*** 

Diskette Number: n 

[Backup] 

e Backup displays this message while backing up files to the specified drive. 
Be sure to label backup disks with the appropriate backup disk number for 
use in restoring them later. 


Bad call format reading (or writing) drive x: 

[MS-DOS device error] 

e The length of the request header passed to the device header was 
incorrect. 


Bad command error reading (or writing) drive x: 

[MS-DOS device error] 

e A device driver issued an incorrect command to the device specified in the 
error message. 


Bad command or file name 

[MS-DOS] 

e The command cannot find the program you asked it to run. 
Check to see that you typed the command line properly, and that the file or 
command is on the disk, or in the command path. 


Bad or missing Command Interpreter 

[MS-DOS] 

e MS-DOS cannot find the command.com file on the disk; either the file is 
missing from the root directory, or the file is invalid. You also receive this 
message if command.com has been moved from the directory it was 
originally in when you started MS-DOS. 

Either restart the system with a disk that contains the command.com file, 
or copy the command.com file from your backup MS-DOS master disk 
onto the disk used to start MS-DOS. 
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Bad or missing filename 
[MS-DOS] 
e You specified a device incorrectly in the config.sys file. 
Check the accuracy of the device command in the config.sys file. 


Bad or Missing Keyboard definition file 


[Keyb] 
e MS-DOS cannot find the Keybxx file that you specified with the Keyb 
command. 


Check to see that the file you specified exists on the disk. Also check to 
see that your path includes the directory in which this file resides. Then, 
retype the command. If you get this message again, the keyboard.sys or 
keyb.com file may be corrupted. 


Bad Partition Table 

[Format] 

e This message means that there is no DOS partition on the hard disk. 
You must run fdisk to create a DOS partition on your hard disk. 


Bad unit error reading drive x: 
[MS-DOS device error] 
e = Invalid subunit numbers were passed to the device driver. 


BREAK Is off (or on) 
[MS-DOS] 
e This message tells you the current setting of Break. 


Cannot CHDIR to path- 

tree past this point not processed 

[Chkdsk] 

e = Chkdsk is checking the structure of the directory and is unable to go to the 
specified directory. All subdirectories underneath this directory will not be 
verified. 

To correct this error automatically, specify the chkdsk /f switch. 


Cannot CHDIR to root 

[Chkdsk] 

èe  Chkdsk is checking the tree structure of the directory and is unable to 
return to the root directory. Chkdsk is not able to continue checking the 
remaining subdirectories. 
Try to restart MS-DOS. If this error persists, the disk is unusable. 
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Cannot CHKDSK a Network drive 
[Chkdsk] 
° You cannot check drives that are redirected over the network. 


Cannot CHKDSK a SUBSTed or ASSIGNed drive 
[Chkdsk] 
e You cannot check drives that have been substituted or assigned. 


Cannot COPY from (or to) a reserved device 


[Xcopy] 
e You cannot copy files from or to a device. 


Cannot create extended DOS partition while logical drives exist 

[Fdisk] 

e Your disk has one or more logical drives assigned to it. These must be 
deleted before you can create an extended DOS partition. 
Delete all logical drives by using fdisk. Then create the extended DOS 
partition. 


Cannot create extended DOS partition without primary DOS 

partition on disk 1 

[Fdisk] 

e You are trying to create an extended DOS partition, but your first hard 
disk does not contain a primary DOS partition. 
First, create the primary DOS partition on your first hard disk. Then, if 
you have more room on that disk, or if you have a second hard disk, you 
can create an extended DOS partition. 


Cannot create a zero cylinder partition 
[Fdisk] 
e You are trying to create a partition with a size of 0 cylinders. 
You must allocate a minimum of 1 cylinder to any partition you create. 


Cannot create Subdirectory BACKUP on drive x: 

[Backup] 

e The disk may be write-protected, full, or the backup subdirectory may 
already exist and be read-only. 
Use another disk as a target disk. 
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Cannot DISKCOMP to or from an ASSIGNed or SUBSTed drive 

[Diskcomp] 

e One of the drives that you specified is a drive that you created using the 
Assign or Subst command. 


Cannot DISKCOMP to or from a network drive 

[Diskcomp] 

e You cannot compare disks on drives that have been redirected over the 
network. 


Cannot DISKCOPY to or from an ASSIGNed or SUBSTed drive 

[Diskcopy] 

e One of the specified drives was created with the Assign or Subst 
command. 


Cannot DISKCOPY to or from a network drive 

[Diskcopy] 

e You cannot copy disks to or from drives that have been redirected over the 
network. 


Cannot do binary reads from a device 

[Copy] 

e The copy cannot be done in binary mode when you are copying from a 
device. 
You should either not use the /b switch, or you should use the /a switch to 
specify an ascii copy. 


Cannot edit .BAK file--rename file 

[Edlin] 

e You attempted to edit a file that had a filename extension of .bak (a 
backup copy created by Edlin). 
If you must edit a file that has an extension of .bak, you must either 
rename or copy the file and give it a different extension. 


Cannot exec BASICA.COM 

[MS-DOS] 

e BASICA cannot be executed by MS-DOS. 
Check to see that the basica.com file is on the disk you are using. If 
basica.com is not in your working directory, make sure that the path 
command points to the directory in which it is located. Try executing 
BASICA again. If you get the same message, the file itself may be bad. 
Try restoring basica.com from backup. 
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Cannot format an ASSIGNed or SUBSTed drive 

[Format] 

e You attempted to format a drive currently mapped to another drive by the 
Assign or Subst command. 
Run assign or subst again and clear all drive assignments. 


Cannot FORMAT a Network drive 
[Format] 
e You cannot format drives that are redirected over the network. 


Cannot FORMAT nonremovable drive x 

[Backup] 

e You are trying to back up files with the /f switch. MS-DOS will not allow 
you to format the target disk specified. 
Be sure you want to back up files to a hard disk. If you do, you must use a 
hard disk that is formatted already. 


Cannot JOIN a Network drive 
[Join] 
e You cannot join drives that are redirected over the network. 


Cannot LABEL a Network drive 
[Label] 
° You cannot label a drive that is shared on a network server station. 


Cannot LABEL a SUBSTed or ASSIGNed drive 

[Label] 

e You cannot label a drive if it has been substituted with the Subst command 
or assigned with the Assign command. 
Check the command line to be sure you specified a valid filename. 


Cannot perform a cyclic copy 

[Xcopy] 

e When you are using the /s switch, you may not specify a target that is a 
subdirectory of the source. 


Cannot recover . entry, processing continued 
[Chkdsk] 
e The"." entry (working directory) is defective and cannot be recovered. 
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Cannot recover .. entry, Entry has a bad attribute (or link or size) 

[Chkdsk] 

e The”".." entry (parent directory) is defective and cannot be recovered. 
If you have specified the /f switch, chkdsk tries to correct the error 
automatically. 


Cannot RECOVER a Network drive 


[Recover] 
e You cannot recover files on drives that are redirected over the network. 


Cannot SUBST a Network drive 
[Subst] 
° You cannot substitute drives that are redirected over the network. 


Cannot SYS to a Network drive 

[Sys] 

e You cannot transfer the system files to drives that are redirected over the 
network. 
For more information about the net print command, see the Microsoft 
Networks User's Guide. 


Cannot use FASTOPEN for drive x: 

[Fastopen] 

e Fastopen works only with local, fixed disks and can work with a maximum 
of four disks at a time. You may be trying to use Fastopen over a network, 
with a floppy disk, or with more than four disks at one time, none of which 
is possible with Fastopen. 


Cannot use PRINT-Use NET PRINT 
[Print] 
e You must use the Net Print command to print files. 


CHDIR .. failed, trying alternate method 

[Chkdsk] 

e When checking the tree structure, Chkdsk was not able to return to a 
parent directory. It will try to return to that directory by starting over at 
the root and searching again. 


XXXXXXX Code page drive cannot be initialized 

[MS-DOS] 

e MS-DOS cannot start either the printer.sys or display.sys program. 
Check the device command line in your config.sys file. You probably 
included an illegal parameter. For more information, see Appendix C, 
"Installable Device Drivers.” 
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Code page not prepared 

[Mode] 

e You have selected a code page that has not yet been prepared for the - 
system, or one that does not have the correct font to support the current 
video mode. 

To prepare a code page for the system, use the mode prepare command. 
If you have installed the display.sys installable device driver, be sure the 
device command line in your config.sys file allows for additional subfonts. 
For more information, see Appendix C, “Installable Device Drivers,” and 
Appendix B, "How to Configure Your System." 


Code page xxx not prepared for all devices 

[Chcp] 

e You have selected a code page that is not currently supported by a device. 
First, be sure your device supports code page switching, and that it is 
currently on-line. If the device supports code page switching, use the 
mode prepare command to prepare the device for the code page. Then 
retry the chcp command. 


Code page xxx not prepared for system 

[Chep] 

e Chep is unable to select a code page for the system. 
First, make sure that nisfunc is installed. If you have not used the device 
command in your config.sys file to install device drivers, you may now 
retry the chep command. If you are using installable device drivers with 
your system, you must use the mode prepare command to prepare the 
specific code page for each device on your system. Then retype the chep 
command. 


Code page operation not supported on this device 

[Mode] 

e You have specified a device and code page combination which MS-DOS 
does not recognize as valid. 
Check to see that the device you specified exists and that you have listed a 
valid code page. Also check to see that that code page is supported on that 
device. 


Code page requested xxx is not valid for given keyboard code 
[Keyb] 
e The keyboard code and code page specified are not compatible. 

Retype the keyb command with compatible keyboard code and code page. 
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Code page specified has not been designated 

[Keyb] 

e You have typed the Keyb command with an option the system doesn't 
recognize. You must first prepare the associated code page for your 
console screen device. 

Use the mode prepare command to prepare the associated code page for 
CON. Then retype the keyb command. 


Code page specified has not been prepared 

[Keyb] 

e You have typed the Keyb command with an option the system doesn't 
recognize. You must first prepare the associated code page for your 
console screen device. 

Use the mode prepare command to prepare the associated code page for 
CON. Then retype the keyb command. 


Code page specified is inconsistent with invoked code page 

[Keyb] 

e This warning message lets you know that the Keyb option you've selected 
does not coincide with the code page for your console screen device 
(CON). 

Use the mode select command if you also want to change the code page 
for CON. 


Code page specified is inconsistent with selected code page 

[Keyb] 

e This warning message lets you know that the Keyb option you've selected 
does not coincide with the code page for your console screen device 
(CON). 

Use the mode select command if you also want to change the code page 
for CON. 


Code page xxx 
[Mode] 
e This is the code page currently being used by the device specified. 


Code pages cannot be prepared 

[Mode] 

e You have either specified a duplicate code page for this device or tried to 
prepare more than the total number of code pages supported for this 
device. 

Check the device command line in your config.sys file to see how many 
prepared code pages are allowed for this device. Use the /status option of 
the mode command to find out which code pages are already prepared for 
this device. For more information, see Appendix B, "How to Configure 
Your System" and Chapter 3, "MS-DOS Commands.” 
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Compare another diskette (Y/N)? 

[Diskcomp] 

e Diskcomp displays this message when it has completed its comparison of 
the disks. 
Type Y (for Yes) if you want to compare more disks; or type N (for No) if 
you don’t. 


Compare error on disk side s, track t 

[Diskcomp] 

e Diskcomp found a difference on the disk in the specified drive, side s, 
track t. 


Compare OK 
[Diskcomp] 
e Diskcomp displays this message if the disks are identical. 


Compare process ended 


[Diskcomp] 
e Diskcomp displays this message if a fatal error occurred during the 
comparison. 


Comparing ¢ tracks n sectors per track, s side(s) 
[Diskcomp] 
e This message confirms the format of the disks that you are comparing. 


COM port does not exist 
[Mode] 
e You have specified an invalid COM port. 


Contains n non-contiguous blocks 

[Chkdsk] 

e = The disk contains fragmented files. 
If you want to copy this disk, you should use the copy or xcopy command 
instead of the diskcopy command. The new copy will then store the new 
files sequentially. 


Content of destination lost before copy 

[Copy] 

e The source file that you specified in the Copy command was overwritten 
before the copy process completed. 
Refer to the copy command for the proper syntax. 
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Convert lost chains to files (Y/N)? 

[Chkdsk] 

e  Chkdsk displays this message if it finds information on the disk that isn't 
allocated properly in the disk’s File Allocation Table. 
If you type Y (for Yes) in response to this prompt, chkdsk recovers the 
lost blocks it found when checking the disk. Chkdsk then creates a proper 
directory entry and a file for each lost chain with a filename of the form: 
filennnn.chk. If you type N (for No), chkdsk frees the lost blocks so that 
they can be reallocated and does not recover any data that was in those lost 
blocks. 


Copy another diskette (Y/N)? 

[Diskcopy] 

e The Diskcopy command has completed processing. 
Type Y (for Yes) if you want to copy another disk, or type N (for No) if 
you don’t. 


Copying ¢ tracks n Sectors/Track, s Sides 
[Diskcopy] 
e Diskcopy displays this message during copying. 


Copy process ended 
[Diskcopy] 
e Diskcopy could not copy the entire disk. 
Use the copy or xcopy command to copy specific files onto the disk. 


Copyright 1981 ,82,83,84,85,86,87 Microsoft Corp. 
[MS-DOS] 
e This message appears on most MS-DOS utility and command banners. 


Corrections will not be written to disk 


[Chkdsk] 
> There are errors on the disk, but Chkdsk will not correct them because you 
did not specify the /f switch. 


You must specify the chkdsk/f switch to correct disk errors. 


Current code page settings 

[Mode] 

© This informational message shows current and prepared code pages for 
the device specified and for the system. 
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Current date is mm-dd-yy 

[Date] 

e ` The Date command displays this message. 
Enter the correct date and press the RETURN key. 


Current keyboard code: xx code page: yyy Current CON code 

page: zzz 

[Keyb] 

e This message displays the current keyboard code and its associated code 
page, and current code page used by your console screen device (CON). 


Current keyboard does not support this code page 

[Keyb] 

e The code page selected is not compatible with the current keyboard code. 
Check the code page you have selected. If it is correct, change the 
keyboard code with the keyb command. 


Current time is hh:mm:ss.hh 

[Time] 

e The Time command displays this message. 
Enter the correct time and press the RETURN key. 


Data error reading drive x: 

[MS-DOS device error] 

e MS-DOS could not read the data from the disk properly. This is often due 
to a defective disk. 
Try typing R (for Retry) several times, or type A (for Abort) to end the 
program. (It’s a good idea to make a new copy of the disk, because if it’s 
defective, you may lose information.) 


Delete current volume label (Y/N)? 

[Label] 

e Ifa current volume label exists, Label displays this message in response to 
the prompt to enter the new volume label for this disk. 
If you want to delete the volume label, type Y (for Yes); otherwise, type N 
(for No). 


XXXXXXXX device driver cannot be initialized 

[MS-DOS] 

e You are trying to install a device driver by using a device command line in 
your config.sys file. The syntax on that command line is wrong. 
See Appendix C, “Installable Device Drivers," for the correct syntax of 
MS-DOS installable device drivers. 


Appendix F MS-DOS Message Directory F.15 


Device Error during Status 
[Mode] 


MS-DOS found an error with the specified device when it was checking 
the status of that device. The problem may be due to a device that does not 
support code pages, a device not properly prepared for code page 
switching, a device which cannot support more code pages than those 
already prepared, or a device with a bad or irregular font file. 

Check the device command line in your config.sys file. Make sure that the 
command syntax and limits for subfonts and additional code pages are all 
correct. Also check to see if your device supports code page switching. 
Consult the hardware vendor if you are unsure. 


Device Error during Prepare 
[Mode] 


MS-DOS found an error with the specified device when preparing that 
device for code page switching. The problem may be due to a device that 
does not support code pages, a device not properly prepared for code 
page switching, a device which cannot support more code pages than 
those already prepared, or a device with a bad or irregular font file. 
Check the device command line in your config.sys file. Make sure that the 
command syntax and limits for subfonts and additional code pages are all 
correct. Also check to see if your device supports code page switching. 
Consult the hardware vendor if you are unsure. 


Device Error during Select 
[Mode] 


MS-DOS found an error with the specified device. The problem may be 
due to a device that does not support code pages, a device not properly 
prepared for code page switching, a device which cannot support more 
code pages than those already prepared, or a device with a bad or 
irregular font file. 

Check the device command line in your config.sys file. Make sure that the 
command syntax and limits for subfonts and additional code pages are all 
correct. Also check to see if your device supports code page switching. 
Consult the hardware vendor if you are unsure. 
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Device Error during write of font file to device 

[Mode] 

e MS-DOS found an error when it tried to write the font file to the specified 
device. The problem may be due to a device that does not support code 
pages, a device not properly prepared for code page switching, a device 
which cannot support more code pages than those already prepared, or a 
device with a bad or irregular font file. 

Check the device command line in your config.sys file. Make sure that the 
command syntax and limits for subfonts and additional code pages are all 
correct. Also check to see if your device supports code page switching. 
Consult the hardware vendor if you are unsure. 


Device or code page missing from font file 

[Mode] 

e MS-DOS did not find a definition of the indicated code page for this 
device in the font file. 
Use the mode command to specify another code page for this device. Also 
check to see that the font file supports the code page you want to use. This 
error also may cause specified code pages to be undefined. Use the mode 
command to prepare and refresh lost code pages. 


Device ddd not prepared 
[Mode] 
e No code page has been prepared for this device. 


DEVICE Support Not Present 
[Diskcomp][Diskcopy] 
e The disk drive does not support MS-DOS 3 3 device control. 


Directory is joined 

[Chkdsk] 

èe  Chkdsk does not process directories that are joined. 
Use the join /d command to "unjoin” the directories, and then run chkdsk 
again. 


Directory is totally empty, no. or .. 

(Chkdsk] 

© The specified directory does not contain references to working and parent 
directories. 
Delete the specified directory and recreate it. 


Directory not empty 
[Join] 
e You can only join onto an empty directory. 
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Disk error reading (or writing) drive x: 

[MS-DOS device error] 

e MS-DOS could not read the data from the disk properly. This is often due 
to a defective disk. 
Try typing R (for Retry) several times, or type A (for Abort) to end the 
program. (It’s a good idea to make a new copy of the disk, because if it’s 
defective, you may lose information.) 


Disk error reading (or writing) FAT 

{Chkdsk] 

e One of your File Allocation Tables has a defective sector in it. MS-DOS 
automatically uses the other FAT. 
You should copy all your files onto another disk. To correct this error 
automatically, you simply specify the chkdsk /f switch. 


Diskette bad or incompatible 

[Diskcopy] 

e The source disk is not formatted, or was formatted incorrectly. You cannot 
copy it. 


Disk full. Edits lost 

[Edlin] 

e  Edlin was not able to save your file due to lack of disk space. 
You should always make sure that there is enough room on the default 
disk to save your file before you use the Edlin E (end) command. You 
should also make sure that the default disk is not write-protected. 


Disk unsuitable for system disk 

[Format] 

e The Format program detected a bad track on the disk where system files 
Should reside. 
You should use this disk to store data only. 


Do not specify filename(s) 
Command format: DISKCOMP d: d:[/1][/8] 


[Diskcomp] 
e You specified an incorrect switch or gave a filename in addition to a drive 
name. 


Do not specify filename(s) 

Command format: DISKCOPY d: d:[/1] 

[Diskcopy] 

e You specified an incorrect switch or gave a filename in addition to a drive 
name. 
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Do you see the leftmost 0? (Y/N) 


[Mode] 
e Mode displays this message to help you align the test pattern on your 
screen. 


Type Y (for Yes) if you can see the leftmost 0 in the test pattern, or type N 
(for No) if you want to shift the display to the nght. 


Do you see the rightmost 9? (Y/N) 


[Mode] 
e Mode displays this message to help you align the test pattern on your 
screen. 


Type Y (for Yes) if you can see the rightmost 9 in the test pattern, or type 
N (for No) if you want to shift the display to the left. 


Do you wish to use the maximum size for a DOS partition and 

make the DOS partition active (Y/N)........ i 

[Fdisk] 

e You are formatting your hard disk. 
Type Y (for Yes) and press the reTurN key if you want to format your 
entire hard disk as the primary DOS partition. Otherwise, type N (for No) 
and press the RETURN key. 


Does name specify a file name or directory name on the target 

(F = file D = directory)? 

[Xcopy] 

e Xcopy displays this prompt if the target directory does not exist. 
Type F if the name specifies a file, or D if the target specifies a directory 
that does not currently exist. 


(.)(..) Does not exist 
[Chkdsk] 
© = This is an informational message from Chkdsk, indicating that either the 


woe 


." or ".." directory entry is invalid. 


DOS 2.0 or later required 
{Attrib][Backup][Fc]{Graphics] [Join][Mode][Restore][Subst] 
e You cannot use these utilities with 1 xx versions of MS-DOS. 


Drive D already deleted 
[Fdisk] 
e You tried to delete drive D, but it had already been deleted. 


Drive deleted 
[Fdisk] 
e You deleted a hard drive from the system. 
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Drive has been changed or deleted 
[Fdisk] 
e You changed or deleted a hard drive on the system. 


Drive letter must be specified 

[Format] 

e You did not specify the drive letter for the drive that you want to format. 
You must specify the name of the drive that you want to format. 


Drive x: not ready Make sure a diskette is inserted into the drive 
and the door Is closed 

[Diskcomp][Diskcopy] 

e The drive is empty, or you did not close the door of the disk drive. 


Drive types or diskette types not compatible 

[Diskcomp][Diskcopy] 

e You must have the same size and type of disks to run these commands. For 
example, you cannot copy from a single-sided disk to a double-sided disk, 
or compare a high-density disk with a low-density disk. 

You should use fe if you want to compare the files on the disks. If you 
want to copy the disk, you can use copy or xcopy, or reformat the target 
disk so that it’s the same type as the source disk, or use a disk of the same 


type. 


Duplicate file name 

[Rename] 

e You tried to rename a file to a filename that already exists, or the name 
you specified could not be found. 


ECHO Is off (or on) 
[MS-DOS] 
© This message tells you the current status of Echo. 


End of input file 

[Edlin] 

© The entire file was read into memory. If the file was read in sections, this 
message indicates that the last section of the file is in memory. 
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Enter current Volume Label for drive x: 

[Format] 

e Format asks you to enter the current volume label for verification before it 
formats the hard disk in the specified drive. 
If you do not know what the volume label is, press conTROL-c to abort this 
command, and give the vol command for the specified drive. Then give 
the format command again. 


Enter new date: 

[Date] 

e You must respond to this prompt when you start MS-DOS, or when you 
use the Date command. 
Type the date in the format indicated by the prompt, or press the RETURN 
key to accept the current date. 


Enter new time: 

[Time] 

e You must respond to this prompt when you start MS-DOS. 
Type the time in the format indicated by the prompt, or press the RETURN 
key to accept the current time. 


Entry error 
[Edlin] 
e The last command you typed contained a syntax error. 
Retype the command with the correct syntax and press the RETURN key. 


Entry has a bad attribute (or link or size) 

[Chkdsk] 

e This message may be preceded by one or two periods that show which 
subdirectory is invalid. 
If you have specified the /f switch, chkdsk tries to correct the error 
automatically. 


Error during read of Font file 
[Mode] 
e MS-DOS found an error when it tried to read the font file for the code 


page specified. 
Error in country command 


[MS-DOS] 
e You used the incorrect syntax for the Country command in your config.sys 
file. 


For the correct syntax of this configuration command, see Appendix B, 
"How to Configure Your System.” 
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Error in .EXE file 
[MS-DOS] 

e The .exe file you have asked MS-DOS to load has an invalid internal 
format. 
You cannot run this program. Check to make sure that you are using the 
correct version of MS-DOS. 


Error opening log file 

[Backup] 

e MS-DOS cannot open the backup log file. 
Check the drive and path sepcified with this command. Remember that the 
log file cannot be located on the target drive. If you did not specify a 
filename for the log, then the error occured when MS-DOS tried to open 
and create backup.log on the source disk. 


Error reading/writing partition table 
[Format] 
e Format could not read or write the partition table. 
You should run fdisk on the disk and then try formatting it again. 


Errors found, F parameter not specified 

Corrections will not be written to disk 

[Chkdsk] 

e  Chkdsk found errors on the disk. If you have not specified the /f switch, 
Chkdsk continues printing messages but will not correct the errors. 
You should run chkdsk with the /f switch if you want to correct the 
problems encountered by the chkdsk command. 


Errors on list device indicate that it may be off-line. Please check it. 
[Print] 
e Your printer is not turned on. 


Error trying to open backup log file 

Continuing without making log entries. 

[Backup] 

e You specified the Backup /L switch, but Backup could not create the 
backup log file. 


Error writing to device 

[MS-DOS] 

° You tried to send too much data to a device, so MS-DOS was unable to 
write the data to that device. 
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EXEC failure 

[MS-DOS] 

e MS-DOS either found an error when reading a command, or the Files 
command in the config.sys file is set too low. 
Increase the value of the files command in the config.sys file, and restart 
MS-DOS. 


Extended DOS partition already exists 
[Fdisk] 
e You cannot create another extended DOS partition. 


Extended DOS partition created 
[Fdisk] 
e You have created an extended DOS partition on your hard disk. 


Extended DOS partition deleted 
[Fdisk] 
e You have deleted an extended DOS partition from your hard disk. 


Failure to access code page font file 

[Mode] 

e MS-DOS cannot open the font file for the specified code page. 
Check to see that you typed font file name, and its pathname correctly. 
Also check the config.sys file to see that the device driver for this device 
has been properly installed. If the config.sys file is incorrect, correct it and 
restart MS-DOS before retyping the mode command. 


Failure to access country.sys 

[Select] 

e MS-DOS cannot open the country.sys file. 
Check to see that your path points to the directory in which country.sys 
resides. Then retype the command. 


Failure to access device: xxx 

[Mode] 

© You are trying to specify a code page for a particular device, but MS-DOS 
cannot access the device listed. 
Retype the command using an existing device. Make sure you are typing 
the device name correctly. 


Failure to access keyboard.sys 
[Select] 
e MS-DOS cannot open the keyboard.sys file. 
Be sure keyboard.sys exists on your source disk. 
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Fastopen already installed 
[Fastopen] 
e Fastopen is already installed on the system. 


Fastopen installed 


[Fastopen] 
e This informational message acknowledges that you have just installed 
Fastopen. 


FCB unavailable reading (or writing) drive x: 

[MS-DOS device error] 

e Anunusual error has occurred. This error usually requires an 
experienced programmer to fix it. 
Type R (for Retry) or A (for Abort). 


fc: cannot open filename-No such file or directory 

[Fc] 

e One of the files that you specified doesn't exist. 
Check the directory for the correct filename. 


fc: filename longer than filename 

[Fc] 

e After reaching the end of one of the files in a file comparison, the other file 
still has data left that was not yet compared. 


fc: incompatible switches 

[Fc] 

e You have specified switches that are not compatible. (For example, [b and 
IL.) 


You should not combine binary and ascii comparison switches. 


fc: no differences encountered 
[Fe] 
e The files are the same. 


fc: out of memory 
[Fc] 
e You do not have enough memory to perform the comparison. 


File allocation table bad 
[MS-DOS] 
e The disk may be defective. 

Run chkdsk /f to check the disk. 
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File allocation table bad drive x: 

[Chkdsk] 

e This message means that the disk was not formatted or was formatted 
improperly. It could also mean that an operating system other than MS- 
DOS is on the disk. 

Run chkdsk /f to check the disk. If this message is displayed again, you 
must reformat the disk. 


File filename canceled by operator 

[Print] 

e MS-DOS displays this message when you specify the /t switch with the 
Print command. 


File cannot be converted 
[Exe2bin] 
e = The input file is not in the correct format. 


File cannot be copied onto itself 


[Copy}[Replace}[Xcopy] 
e The source filename you specified is the same as the target filename. 


File creation error 

([MS-DOS]{Edlin][Restore][Xcopy] 

e You tried to add a new filename or replace a file that already exists in the 
directory, or there was not enough space for the file. If the file already 
exists, it is a read-only file and cannot be replaced. This error message 
may also occur if the root directory is full, out of files, or if the filename is 
the same as a volume or directory, or a hidden (or system) file. 


File is READ-ONLY 
[Edlin] 
e The file is designated read-only, so you may not change it. 


File name must be specified 
[Edlin] 
e You did not specify a filename when you started Edlin. 
You should type the Edlin command followed by a filename. 


File not found 

[Chkdsk][{Edlin][Fe][Find][Print][Recover][Rename][Xcopy] 

e MS-DOS could not find the file that you specified, or you tried to rename a 
file with a name already in the directory. 
Check to see that you entered the filename correctly. 


Appendix F MS-DOS Message Directory F.25 


File not in PRINT queue 

[Print] 

e The file that you specified was not in the print queue, so you cannot 
remove it from the queue. 
Check to see that you entered the filename correctly. 


Files cannot be added to this diskette 

Unless the PACK (/P) switch is used 

Set the switch (Y/N)? 

[Backup] 

e The target disk does not have enough room for any of the files on the 
source disk without dividing them across disks. 
If you do not want to divide a file across disks, type N (for No). If your 
files are larger than will fit on one floppy disk, you must type Y (for Yes). 


***Files were backed up at time on date*** 
[Restore] 
e This is an information message only. 


FIND: Access denied 
[Find] 
èe You cannot access the file. 
Make sure that the disk is not write-protected, read-only, or locked. 


FIND: File not found 

[Find] 

e MS-DOS could not find the file that you specified. 
Make sure you have typed the filename correctly. 


FIND: Invalid number of parameters 
[Find] 
e You specified either too many or too few options in the command line. 


FIND: Invalid Parameter 
[Find] 
© One of the switches you specified is wrong. 


FIND: Read error in filename 
[Find] 
e = The Find command could not read the specified file. 


FIND: Syntax error 
[Find] 
e Check to make sure that you have typed the command correctly. 
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First cluster number is invalid, entry truncated 

[Chkdsk] 

e The file directory entry contains an invalid pointer to the data area. If you 
specified the /f switch, the file is truncated to a zero-length file. 


FIRST diskette bad or incompatible 

[Diskcomp] 

e Diskcomp cannot recognize the format on the source disk. 
You should run chkdsk to help you identify the problem. 


Fixups needed-base segment hex: 

[Exe2bin] 

e The source (.exe) file contained information indicating that a load 
segment is required for the file. 
You must specify the absolute segment address where the finished module 
is to be located. 


Font File contents Invalid 

[Mode] 

e MS-DOS cannot use the contents of the font file specified. 
Make sure you are typing the name of the font file correctly. Retype the 
command. If this message is displayed again, your font file may have been 
altered or corrupted. Recopy this file from the master MS-DOS disk. Type 
the command again. This error may also cause existing selected code 
pages to be undefined. Use the mode command to prepare these code 
pages again, and to refresh them. 


For cannot be nested 
[MS-DOS] 
e You cannot nest For commands in a batch file. 


Format another (Y/N)? 

[Format] 

e Format displays this message when it has finished formatting a disk. 
Type Y (for Yes) if you want to format another disk, or type N (for No) if 
you don’t. If you accidentally type Y, you can abort the format process by 
typing CONTROL-c in response to the message "Strike any key.” 
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Format complete 

[Format] 

e Format displays this message when it has finished formatting the disk in 
the specified drive. 


Format failure 

[Format] 

e MS-DOS could not format the disk. This message is usually displayed with 
an explanation as to why the command failed. 


Format not supported on drive x: 
[Format] 
e You cannot use Format to format this drive. 
You may have specified device parameters that your computer cannot 


support. 


Formatting while copying 
[Diskcopy] 
è Diskcopy displays this message if the target disk has never been formatted. 


General failure reading (or writing) drive x: 

[MS-DOS device error] 

è An unusual error has occurred. This error usually requires an 
experienced programmer to fix it. 
Type R (for Retry) or A (for Abort). 


Graftabl needs DOS version 2.0 or later 
[Graftabl] 
e You cannot use Graftabl with 1 xx versions of MS-DOS. 


Graphics characters already loaded 

(Graftabl] 

e The Graftabl command displays this message if you have already loaded 
the table of graphics characters into memory. 


Graphics characters loaded 

[Graftabl] 

e The Graftabl command displays this message after it loads the table of 
graphics characters into memory. 


Hardware code pages: 

Prepared code pages: 

[Mode] 

e This message lists the current code pages prepared for the device 
specified. 
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Has invalid cluster, file truncated 

[Chkdsk] 

e The file directory entry contains an invalid pointer to the data area. If you 
specified the /f switch, the file is truncated to a zero-length file. 


Head: hhh Cylinder: ccc 


[Format] 
e Format displays the head and cylinder number of the track currently being 
formatted. 


Illegal device name 
[Mode] 
e Your computer does not recognize this device name. 


Incompatible system size 

[Sys] 

e The system files occupy more space onthe source disk than is available on 
the target disk. 
You cannot use the sys command to transfer the system files to this disk. 


Incorrect APPEND Version 

[MS-DOS] 

e You are not using the MS-DOS 3.3 append command. You are using 
another incompatible version. 


Incorrect DOS Version 
[Append][Attrib][Backup][(Chkdsk][Diskcomp][Diskcopy] 
[Edlin}[Fe][Find][Format][Graphics][Join][Keybxx] 

[Label ][Mode](More]{Print][Recover]{Replace][Restore] 

[Share][Sort}[Subst][Sys][Tree][Xcopy] 

e Some MS-DOS utilities will not run on older versions of the operating 
system, and many are written to run only on the exact version of MS-DOS 
that they were created for. 

You must use the correct version of MS-DOS to run this command. 


Incorrect DOS Version, use DOS 2.00 or later 


[Link] 
e Some MS-DOS utilities will run only on MS-DOS version 2.00 or later 
versions. 


Incorrect number of parameters 
[Join][Subst] 
e You specified either too many or too few options in the command line. 


Appendix F MS-DOS Message Directory F.29 


Incorrect parameter 
[Assign][Share] 
e One of the options you specified is wrong. 


Infinite retry on parallel printer timeout 

[Mode] 

e Your printer is probably off-line or not ready. 
If the printer appears to be ready, you may have to press the CONTROL-ALT- 
DELETE keys to reset the computer. 


Insert backup diskette n into drive x: 

[Backup][Restore] 

e This message prompts you for the nth backup disk. 
Put the next disk into the specified drive. Be sure to label each backup 
disk in the appropriate order for use when restoring the files. 


Insert destination disk in drive x: 

and strike any key when ready 

[Sys] 

e This message appears when you are using Sys to transfer the operating 
system with a single disk drive. 
You should insert a disk in the appropriate drive and press any character 
or number key to begin processing. 


Insert diskette for drive x: 

and strike any key when ready 

[MS-DOS] 

e This message appears when MS-DOS is copying and formatting. 
You should insert a disk in the appropriate drive and press any character 
or number key to begin processing. 


Insert diskette with batch file 

and press any key when ready 

[MS-DOS] 

e = The disk containing your batch file is not in the drive you originally 
specified. 
Reinsert the disk that contains the batch file in the appropriate drive. 
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Insert DOS diskette in drive x: 

and strike ENTER when ready 

[Format] 

e You typed the Format |s command, but the disk in the default drive does 
not contain MS-DOS system files. 
Insert a disk with the files io.sys and msdos.sys in the drive specified and 
press any key. 


Insert FIRST diskette into drive x: 
[Diskcomp] 
e This message prompts you for the first disk that you want to compare. 


Insert last backup diskette in drive x: 

Strike any key when ready 

[Backup] 

e This message prompts you for the final backup disk. 
After you have put the final backup disk into the drive specified, press any 
alphanumeric key to continue the backup process. 


Insert restore target diskette into drive x: 

[Restore] 

e Restore displays this prompt if you are restoring files to a floppy. 
Put the target disk into the specified drive. 


Insert SECOND diskette into drive x: 

[Diskcomp] 

e This message prompts you for the disk that you want to compare with the 
first disk. 


Insert source disk 
[Backup] 
e This message prompts you to put the source disk into the drive. 


Insert SOURCE diskette into drive x: 


[Diskcopy] 
e This message prompts you to put the disk to be copied into the specified 
drive. 


Insert system diskette in drive x: 

and strike any key when ready 

[Sys] 

e Sys needs a disk from which to read the io.sys and msdos.sys files. 
Insert a system disk into the specified drive and press any character or 
number key to start the system copy process. 
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Insert TARGET diskette into drive x: 

[Diskcopy]} 

e Diskcopy displays this message to prompt you to place the target disk into 
the specified drive. If your computer has one floppy drive, this message 
prompts you to put the proper disk into the drive. 


Insufficient disk space 

[MS-DOS]|[Replace][Sort][Xcopy] 

e The disk is full and does not contain enough room to perform the specified 
operation. 


Insufficient memory 
[Backup][Chkdsk][Diskcomp][Diskcopy]|Edlin][Replace] 
[Restore][Sort][Xcopy] 
e There is not enough memory in your computer to perform the specified 
operation. 
Before retrying this operation, you must free memory by deleting files. In 
Edlin, you may be able to free memory by typing a W (write) command 
followed by an A (append) command. 


Insufficient memory for system transfer 

[Format] 

e Your memory configuration is insufficient to transfer the MS-DOS system 
files io.sys and msdos.sys with the Format /s switch. 


Insufficient room in root directory. 

Erase files in root and repeat CHKDSK 

[Chkdsk] 

e = Chkdsk always recovers lost files into the root directory. In this case, your 
root directory is full. 
Delete some files in your root directory, or move them to another directory 
to make room for the lost files. 


Intermediate file error during pipe 

[MS-DOS] 

è The pipe operation uses temporary files on the disk that are deleted 
automatically once the piping process is complete. An error has occurred 
in one of these files. 

Make sure that there is enough room on the disk for the temporary file and 
that the disk is not write-protected, and try the command again. 
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Internal error 
[Fc][Mode] [Share] 
e This message indicates an error in the utility. 


Internal stack overflow 

System Halted 

[MS-DOS] 

e The system tried to use more stacks than were available. This caused a 
series of hardware interrupts and halted the system. 
Restart MS-DOS. Then edit your config.sys file and allocate more stack 
resources. For more information, see Appendix B, "How to Configure 
Your System." 


Invalid argument 

[Backup]}[Fc][Restore] 

e You have specified an invalid argument. 
Refer to Chapter 3, "MS-DOS Commands,” for the correct syntax of the 
command, and try again. 


Invalid baud rate specified 

[Mode] 

e You have specified an incorrect baud rate. Valid choices are 110, 150, 
300, 600, 1200, 2400, 4800, and 9600. 
You must specify at least the first two digits of the baud rate. 


Invalid characters in volume label 
[Format][Label] 
e The volume label should only contain up to 1] alphanumeric characters. 


Invalid code page specified 

[Chep] 

e You selected an invalid code page number. 
Retype the command with the correct code page. 


Invalid COMMAND.COM 

Insert COMMAND.COM disk in default drive and strike any key 

when ready 

[MS-DOS] 

e The program you have just run used up almost all of available memory. 
MS-DOS must now reload the command.com file from disk. However, 
either MS-DOS cannot find command.com on the disk, or the copy it has 
found is the incorrect version. 

Insert a disk that contains a copy of command.com into the default drive (it 
must be the same version with which you started MS-DOS). 
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Invalid country code 

[MS-DOS] 

e In your config.sys file you have specified a country number that is not in 
the table of files configured in this version of MS-DOS. Country codes 
must be in the range 1-999 and are set by your computer manufacturer. 


Invalid country code or code page 


[MS-DOS] 
e MS-DOS found an invalid country code or code page number in your 
config.sys file. 


Correct the country command line in your config.sys file. 


Invalid current directory 

[Chkdsk] 

e Your disk has an invalid directory on it. 
You may be able to recover some of the files on this disk by copying them 
with the copy command. Otherwise, you must replace the disk. 


Invalid date 

[Date] [Xcopy] 

e You specified an invalid date in response to the date prompt. 
Enter a valid date. Refer to Chapter 3, "MS-DOS Commands," for the 
proper syntax of the date command. 


Invalid Date/Time 

[Backup] 

e You specified an invalid date with one of the Backup command switches. 
Refer to Chapter 3, "MS-DOS Commands,” for the proper syntax of the 
backup command, then try again. 


Invalid device 
[MS-DOS] 
e The device specified was not AUX, CON, NUL, or PRN. 


Invalid device parameters from device driver 

[Format] 

e Format displays this message when the number of hidden sectors is not 
evenly divisible by the number of sectors per track (that is, the partition 
does not start on a track boundary). This might happen if you tried to 
format a hard disk that previously had been formatted with MS-DOS 2.x 
without first running Fdisk, or if you have set the device driver parameters 
incorrectly. 

Check the config.sys file for incorrect device or drivparm commands. 
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Invalid directory 

[MS-DOS] 

e The directory you specified either does not exist or is invalid. 
Check to see that you entered the directory name correctly. 


Invalid disk change reading (or writing) drive x: 

[MS-DOS device error] 

e You changed the disk in a drive when you weren't supposed to. 
Put the disk back in the drive and type R (for Retry). 


Invalid drive in search path 
[MS-DOS] 
e The drive does not exist. 


Invalid drive or filename 


[Edlin][Recover] 
e You did not type a valid drive name or filename. Enter a valid drive name 
or filename. 


Invalid drive specification 
[Backup][Chkdsk][Diskcomp][Diskcopy][Format][Label] 
[Print]{Replace][Restore][Sys][Tree][Xcopy] 
e The drive is incorrect or does not exist. 

Enter a valid drive name. 


Invalid environment size specified 
[Command] 
e You gave an invalid number of bytes with the Je switch. 
You must specify a number between 160 and 32,768 (bytes). 


Invalid keyboard code specified 

[Keyb} 

e You selected an invalid keyboard code with the Keyb command. 
Retype the command with the correct keyboard code. 


Invalid language specified 

[Keyb] 

e You typed an invalid keyboard code with the Keyb command. 
See the keyb command in Chapter 3, "MS-DOS Commands,” for a list of 
valid keyboard codes. Retype the command using a valid keyboard code. 
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Invalid number of parameters 

[Attrib] [Backup][Fc][Find][Recover][Restore][Xcopy] 

e Either you did not specify an option or string, or you specified the wrong 
number of options in the command line. 


Invalid parameter(s) 
[Backup][Chkdsk][Diskcomp][Diskcopy][Edlin][Find] 
[Format][Join][Mode][Print]{Replace][Restore][Sort] 
[Subst][Sys][Tree][Xcopy] 
e One of the switches you specified is wrong or does not exist. 
Refer to Chapter 3, "MS-DOS Commands," to make sure you are using 
the correct switches. 


Invalid path, not directory, or directory not empty 


[MS-DOS] 
e You are unable to remove the directory requested for one of the specified 
reasons. 


Invalid path (or file not found) 

[Attrib][Backup][Copy][Restore][Tree][Xcopy] 

e You have entered a pathname or filename that does not exist. 
Enter a valid pathname or filename with the command. 


Invalid path or parameter 
[Append] 
e You specified a file or directory that does not exist. 
Enter a valid pathname or filename with the append command. 


Invalid signature in COUNTRY.SYS file 

[Select] 

e Select read the country.sys file to verify the country code. Select quits if it 
cannot find a proper file header or a specific country code. 


Invalid signature in KEYBOARD.SYS file 

[Select] 

e Select reads the keyboard.sys file to verify the keyboard code. Select quits 
if it cannot find the proper file header or a specific keyboard code. 


Invalid STACK parameter 


[MS-DOS] 
© The syntax of the Stack command in your config.sys file includes an 
invalid parameter. 


See Appendix B, "How to Configure Your System,” for the correct syntax 
of that configuration command. 
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Invalid sub-directory entry 
[Chkdsk] 


The subdirectory that you specified either does not exist or is invalid. 


Check whether you typed the subdirectory name correctly. 


Invalid syntax 
[MS-DOS] 


You used the wrong syntax when typing a command. 
See Chapter 3, "MS-DOS Commands," for the correct syntax of an MS- 
DOS command. 


Invalid syntax on DISPLAY.SYS code page driver 
[MS-DOS] 


You used the wrong syntax when you typed the Device command in your 
config.sys file to load display.sys. 

See Appendix B, "How to Configure Your System,” for the correct syntax 
of device. Also see Appendix C, "Installable Device Drivers,” for 
information about the display.sys installable device driver. 


Invalid syntax on PRINTER.SYS code page driver 
[MS-DOS] 


You used the wrong syntax when you typed the Device command in your 
config.sys file to load printer.sys. 

See Appendix B, "How to Configure Your System," for the correct syntax 
of device. Also see Appendix C, "Installable Device Drivers," for 
information about the printer.sys installable device driver. 


Invalid syntax on PRINTER.SYS code page switching device 
drivers 
[Mode] 


You used the wrong syntax when you typed the Device command in your 
config.sys file to load printer.sys. 

See Appendix B, "How to Configure Your System," for the correct syntax 
of device. Also see Appendix C, "Installable Device Drivers," for 
information about the printer.sys installable device driver. 


Invalid time 
[Time] 


You specified an invalid time. 
Refer to Chapter 3, "MS-DOS Commands," for the correct syntax, and try 
the command again. 


Appendix F MS-DOS Message Directory F.37 


Invalid Volume ID 

[Format] 

e Format displays this message if you enter a volume label that doesn’t 
match the label on the hard disk you want to format. It then quits the 
format process. 

Use the vol command to find out what the volume label for the hard disk 
is, then try the command again. 


Invalid working directory 

process cannot continue 

[Chkdsk] 

e The current directory of the disk being checked is damaged and unusable. 


xis not a choice, Please enter y-z 
[Fdisk] 
è You tried to select an invalid option x. 
Select a valid option from the range shown (y-z). 


KEYB has not been installed 

[MS-DOS] 

e No alternate keyboard code has been installed for your system. 
If you want to use keyboard code other than the default U.S. (QWERTY) 
keyboard, use the keyb command to install it. 


Label not found 
[MS-DOS] 
e Your batch file contains a Goto command to a nonexistent label. 


Last backup diskette not inserted 

Insert last backup diskette in drive x: 

Strike any key when ready 

[Backup] 

e This message prompts you for the final backup disk. 
After you have put the final backup disk into the drive specified, press any 
alphanumeric key to continue the backup process. 


** Last file not backed up *** 

[Backup] 

e Backup could not back up the last file on the disk. This message may occur 
if there is no more room on the target disk. It may also occur if there was 
an error in the source file, or on the target disk. 

You may have to back up this file separately to another disk. 
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Line too long 

[Edlin] 

e During an Edlin R (replace) command, the string given as the replacement 
caused the line to expand beyond the limit of 253 characters. 
You should divide the long line into two lines and retry the R command. 


List output Is not assigned to a device 

[Print] 

e When you first type the Print command, MS-DOS asks you what device 
you want to specify as a printer. This message appears if Print is set up for 
a device that does not exist. 


Lock violation reading (or writing) drive x: 

[MS-DOS device error] 

e A program tried to access part of a file that another program was using. 
Type A (for Abort), or wait awhile and type R (for Retry). 


x lost cluster(s) found in y chains 

Convert lost chains to files (Y/N)? 

[Chkdsk] 

e  Chkdsk displays this message if it finds information on the disk that isn't 
allocated properly in the disk’s File Allocation Table. 
If you type Y (for Yes) in response to this prompt, chkdsk recovers the 
lost blocks it found when checking the disk. Chkdsk then creates a proper 
directory entry and a file for each lost chain with the filename of the form: 
filennnn.chk. If you did not specify the /f switch, chkdsk displays: “x 
bytes would be freed." If you type N (for No), chkdsk frees the lost blocks 
so that they can be reallocated and does not recover any data that was in 
those lost blocks. If you did not specify the /f switch, chkdsk does 
nothing. 

Logging to file x 

[Backup] 

e The Backup command is writing a backup log to the file specified. 

Logical DOS drive created, drive letters changed or added 

[Fdisk] 

e You have created or revised one or more logical drives. 
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LPTx: not redirected 
[Mode] 
e Mode could not redirect the parallel printer port. 
Check to see whether you have specified the proper options. 


LPTx: redirected to COMx: 

[Mode] 

© Output on the parallel printer port will now be sent to this asynchronous 
communications port. 


LPTx: set for 80 
[Mode] 
e = The parallel printer port has been set for 80 columns. 


LPTx: set for 132 
[Mode] 
e The parallel printer port has been set for 132 columns. 


Maximum available space for partitions is xxx cylinders 
[Fdisk] 
e = This is an informational message. 


Maximum number of logicai DOS drives installed 

[Fdisk] 

e You have installed the maximum number of logical DOS drives allowed by 
MS-DOS. You may not create any more logical DOS drives. 


Memory allocation error. 

Cannot load MS-DOS, system halted 

[MS-DOS] 

e Restart MS-DOS. 
If this error persists, make a new copy of the MS-DOS disk from your 
backup copy of the system disk. 


Missing from the file is either the device ID or the code page 

[Mode] 

e The code page specified is not supported in the code page information 
(.cpi) file, or the .cpi file does not support the printer specified. 
For a list of valid cplist values in the mode command, see Chapter 3, 
"MS-DOS Commands." 


MODE fff code page function complete 
[Mode] 
e This message is informational only. 
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--More-- 
[More] 
e = Press the sPacEBAR to view more of the file or directory. 


MORE: Incorrect DOS version 
[More] 
e The More command does not run on MS-DOS versions before 2.0. 


Must specify COM1, COM2, COM3 or COM4 
[Mode] 
e You must specify a serial port. 


Must specify destination line number 

[Edlin] 

e You did not specify the destination line number for an Edlin C (copy) or M 
(move) command. 
Retype the command with a destination line number. 


Must specify ON or OFF 
[MS-DOS] 
e The command requires either an ON or an OFF argument. 


Name of list device [PRN]: 


[Print] 
e This prompt appears the first time that Print is run and the /d switch is not 
specified. 


You can specify the name of any valid device, which then becomes the 
print output device. If you press the RETURN key, MS-DOS uses the default 
list device PRN. 


New file 

{Edlin] 

© Edlin prints this message if it does not find a file with the name you 
specified. 
If you are creating a new file, ignore this message. 
If you do not intend to create a new file, check to see whether you have 
correctly typed the name of the file that you wish to edit. 


NLSFUNC already installed 

{Nisfunc] 

è NIisfunc stays resident in memory once it is initialized. You have already 
loaded it into memory. 


Appendix F MS-DOS Message Directory F.41 


No Append 

[Append] 

e No paths have been appended. 
If you would like to append a path for data files, use the append 
command. 


No appended directories 


[Append] 
e You did not specify a path with the Append command. 


No code page has been selected 
[Chep] 
e No code pages have been selected for the system. 
If you would like to select a code page, use the chcp command. 


No COM: ports 

[Mode] 

e Your computer does not have an asynchronous communications (serial) 
port. 


No files added (or replaced) 
[Replace] 
e The Replace command did not add or replace any files. 


No files found filename 
[Replace] 
e Replace could not find matching source or target files. 


No free file handles. 

Cannot start COMMAND.COM, exiting 

[MS-DOS] 

e Restart MS-DOS. 
If this message recurs, increase the files command value in the config.sys 
file. 


No logical drives defined 
[Fdisk] 
© There are no logical drives defined for your system. 


No paper error writing device dev 
[MS-DOS device error] 
e The printer is either out of paper or not turned on. 
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No path 

[Path] 

e You typed Path and pressed the ReTURN key to find out what your search 
path is, but you didn't set a command search path. 


No primary DOS partition to delete 

[Fdisk] 

e You have selected the Fdisk option to delete your primary DOS partition, 
but that partition does not exist. 


No room for system on destination disk 

[Sys] 

e There is not enough room for the system files on the target disk. 
Delete some files to make room for the system files or use another disk. 
You may need to reformat the disk to put the system on it. 


No room in directory for file 

[Edlin] 

e You tried to create or save a file to the root directory, but it is either full, 
or you specified an invalid disk drive or filename. 
Check the command line that you used to start Edlin for an invalid 
filename or disk drive entry. If your command contains no invalid entries, 
you should run the chkdsk program for the specified disk drive. If the 
status report shows that the disk directory is full, and if there is still 
enough memory left on the disk, you may be able to create the file in a 
subdirectory. (This is because subdirectories are not limited in size as is 
the root directory.) Otherwise, remove the disk and replace it with another 
formatted disk. 


No room in root directory 

[Label] 

e There is not enough room in the root directory for a volume label. 
Delete or move some of the files from the root directory to make room for 
the volume label. 


No source drive specified 


[Backup] 
© You must specify a source drive. 
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No space left on device 

[B ackup][Fc][Restore] 
You cannot back up or restore any more files, and you cannot send any 
more output from a file comparison to your disk because the target disk is 
now full. 
You should probably delete some of the files on the disk to make more 
room. 


No space to create logical drive 


[Fdisk] 
e You are trying to create a logical drive, but there is no space available to 
do so. 


No sub-directories exist 


[Tree] 
e You have specified the /s switch, but the directory does not contain 
subdirectories. 


No such file or directory 
[Backup][Fc][Restore] 
o One or more of the files or directories that you specified does not exist. 


No target drive specified 


[Backup] 
e You must specify a target drive for this command. 


No version of Graphic Character Set Table is loaded 
[Graftab}] 
e For information only. 


Non-DOS disk error reading (or writing) drive x: 

[MS-DOS device error] 

e MS-DOS does not recognize the disk format because the disk is missing 
information or contains another operating system. 
Try running the chkdsk command to correct the problem. (See Chapter 3, 
"MS-DOS Commands,” for information about chkdsk.) If running chkdsk 
does not solve the problem, you should reformat the disk by using the 
format command—even though this will destroy all the files on the disk. 


Non-standard version of Graphic Character Set Table is already 

loaded 

[Graftabl] 

e MS-DOS cannot recognize the current table of graphics characters 
because it has been modified since it was loaded. 
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Non-system disk or disk error 
Replace and strike any key when ready 


[Format][Sys] 
e Replace the disk with the proper disk and press any alphanumeric key to 
continue. 


*** Not able to back up (or restore) file *** 


[Backup] 
e This message may occur if there was an error in the source file or on the 
target disk. 


Use the chkdsk command on the source disk to see if you can determine 
the problem. 


Not a graphics printer file 
[Graphics] 
e = The file you are printing does not contain graphics. 


Not enough memory 
(Join][Share] [Subst] 
e There is not enough memory for MS-DOS to run the command. 


Not enough room to merge the entire file 

[Edlin] 

e There was not enough room in memory to hold the file during an Edlin T 
(transfer) command. 
You must free some memory by writing some files to a disk or by deleting 
some files before transferring this file. 


Not found 

{Edlin] 

e You specified an Edlin S (search) or R (replace) command that was unable 
to find a further occurrence of the specified search or replace string. 


Not ready error reading (or writing) drive x: 

[MS-DOS device error] 

e The device (usually a drive or printer) specified in the error message is 
not ready to accept or transmit data. 
This often happens when the disk drive door is open. If this is the problem, 
close the door and type R (for Retry), or check to see if the printer is on 
and ready to print. 
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O.K.? 

[Edlin]} 

e This prompt occurs during Edlin S (search) or R (replace) command 
processing. 
If you press any key except Y (for Yes) or the RETURN key, the search or 
replace process continues. 


One or more CON code pages invalid for given language 

[Keyb] 

e Keyb examined all prepared code pages, and has found that at least one 
code page is incompatible for your screen console device (CON). This is 
only a warning to let you know that your keyboard and screen console 
device are working from different code pages. 


Only non-bootable partitions exist 
[Fdisk] 
e None of the partitions left can boot MS-DOS. 


Only partitions on drive 1 can be made active 

[Fdisk] 

e You are trying to create an active partition on a hard disk other than that 
found on the first hard disk drive. This is not allowed. 


Out of environment space 

{[Command][MS-DOS] 

e There is not enough room in the program environment to accept more 
data. 
To increase the size of the existing environment, use the /e switch with the 
command command or remove some of the existing environment 
variables by using the set command. 


Parameters not compatible 
[Format][Replace] 
e You have specified switches that cannot be used together. 


Parameters not compatible with fixed disk 
[Format] 
ə You have used a switch that is not compatible with the specified drive. 


Parameters not supported 
[MS-DOS][Format] 
e You have specified parameters that MS-DOS does not support. 
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Parameters not supported by Drive 

[Format] 

e Format displays this message when the device driver for this drive does 
not support Generic IOCtl function requests. 


Partition selected (x) is not bootable, active partition not changed 

[Fdisk] 

e You are trying to change active partitions, but MS-DOS cannot be booted 
from the partition selected. 


Path(name) too long 

[Print][Replace][Xcopy] 

e The pathname you specified was too long. 
You may have to change directories to use this command with files in 
deep subdirectories. 


Path not found 
[Chkdsk][Replace}[Subst][Xcopy] 
e You specified an invalid pathname. 


Press any key to begin adding (replacing) file(s) 

[Replace] 

e When you specify the /w switch, Replace displays this message to prompt 
you to start replacing files. 


Press any key to begin formatting x: 

[Format] 

e This prompt is issued before you format a disk. 
Press any key to begin the format process. Or, if you wish to end this 
command, press CONTROL-C. 


Press any key to begin recovery of the n file(s) on drive x: 
[Recover] 
e This prompt is issued before you recover a disk or file. 
Press any key to begin the recovery. Recovered files are named 
filennnn.rec. If you wish to end this command, press CONTROL-C. 


Press any key when ready... 


[Diskcomp][Diskcopy] 
e This prompt gives you time to insert the appropriate disks before copying 
them. 


When you have inserted the disks into the appropriate drives, press any 
key to begin the diskcopy process. Or, if you wish to end this command, 
press CONTROL-C. 
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Previously prepared code page replaced 

[Mode] 

e This command changed the selected code page for a specific device by 
using another prepared code page. 


Primary DOS partition already exists 

[Fdisk] 

e You are trying to create a primary DOS partition, but one already exists. 
If there is space available on your hard disk, try to create an extended 
DOS partition instead. 


Primary DOS partition created 
[Fdisk] 
e You have successfully created a primary DOS partition on your disk. 


Primary DOS partition deleted 
[Fdisk] 
e You have deleted the primary DOS partition from your disk. 


Printer error 
[Mode] 
e = The printer is off, or is not ready to print. 


Printer lines per inch set 
[Mode] 
e Mode has set the number of lines per inch for the printer. 


PRINT queue is empty 
[Print] 
e There are no files waiting to be printed. 


PRINT queue is full 

[Print] 

e = There is only room for 10 files in the list of files waiting to be printed. 
You can make room for more by using the print /q switch. The limit is 32 
files. 


Probable non-DOS disk 

Continue (Y/N)? 

[Chkdsk] 

e The disk you are using is not recognized by this version of MS-DOS. The 
disk was either created by another system with a format that is not 
supported on this version of MS-DOS, or it is not an MS-DOS disk. 

Do not continue processing if chkdsk returns this message for a floppy 
disk. If this message returns for a hard disk, the information describing the 
characteristics of the disk to MS-DOS has been destroyed. In this case, 
you may continue .B chkdsk processing by typing Y (for Yes). This error 
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may mean that the File Allocation Table (FAT) is bad and that the disk is 
unusable. 


Processing cannot continue 

[Chkdsk] 

e There is not enough memory in your machine to run Chkdsk for this disk. 
You must obtain more memory to run chkdsk. 


Program too big to fit in memory 

[MS-DOS] 

e You need more memory to run your application. It is possible that some 
programs you have run are still using some memory. 
You may try to restart MS-DOS; however, if you still receive this 
message, you still need more memory. 


Read error, COUNTRY.SYS 

[MS-DOS] 

e MS-DOS cannot read the country.sys file. 
Retry the command. If you get the same message, the country.sys file is 
probably corrupted. Restore the file from backup. 


Read error in filename 
[Edlin}[Find] 
e MS-DOS could not read the entire file. 


Read error, KEYBOARD.SYS 

[MS-DOS] 

e MS-DOS cannot read the keyboard.sys file. 
Retry the command. If you get the same message, the keyboard.sys file is 
probably corrupted. Restore the file from backup. 


Read fault error reading drive x: 

[MS-DOS] 

e MS-DOS is unable to read data from the device (usually a disk drive). 
Check to see that the disk is properly inserted in the drive, then type R (for 
Retry). 


Reading source file(s)... 


[Xcopy] 
e Xcopy is now reading the source files that you specified. 
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Reinsert diskette for drive x: 
[Format] 
e  Reinsert the disk being formatted in the indicated drive. 


Replace filename? (Y/N) 

[Replace] 

e Replace displays this prompt if you specify the [w switch. 
Type Y (for Yes) if you want to replace the existing file, or type N (for No) 
if you do not want to replace the file. 


Replace the file (Y/N)? 

[Restore] 

e = The file that you want to restore from backup already exists on your target 
disk. 
Type Y (for Yes) and press the RETURN key to overwrite the file. Type N 
(for No) and press the RETURN key if you don’t want to replace the file on 
your target disk with the file from the backup disk. 


Replacing filename 

[Replace] 

e Replace displays this prompt to let you know that it is replacing this file 
that exists on your disk. 


Requested logical drive size exceeds the maximum available space 

[Fdisk] 

e You are trying to create a logical drive that is larger than the space 
available. 


Requested partition size exceeds the maximum available space 

[Fdisk] 

e You are trying to create a partition on your hard drive that is larger than 
the space available. 


Requested Screen Shift out of range 
[Mode] 
e You cannot shift the display any farther. 


Resident part of PRINT installed 

[Print] 

è = This is the first message that MS-DOS displays when you issue the Print 
command. It means that to process the Print command with other 
processes, available memory has been reduced by several thousand bytes. 
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Resident portion of MODE loaded 

[Mode] 

e Part of the Mode program is now resident in memory, and available 
memory has been reduced by several thousand bytes. 


Resident portion of NLSFUNC loaded 

[NIsfunc] 

e Nlsfunc stays resident in memory once it is initialized. This informational 
message lets you know that you have already loaded Nlsfunc into memory. 


Restore file sequence error 

[Restore] 

e You have restored files in the wrong order. 
You must insert the backup disks in the same order that they were backed 
up. 


*** Restoring files from drive x: *** 

Diskette: n 

[Restore] 

e This message is displayed during the restore process. 


Resynch failed. Files are too different 

[Fc] 

e Fe compares what can be loaded into memory. If no lines match in the 
portion of the files in the buffer space, Fc displays this message. 


Same drive specified more than once 

[Fastopen]} 

e You tried to activate Fastopen for the same drive more than once. There is 
no need to reactivate it for the same drive. 


SECOND diskette bad or incompatible 

[Diskcomp] 

e The second disk does not contain the same format as the first disk, or 
Diskcomp does not recognize the format of the second disk. 
You should run chkdsk to help you identify the problem. 


Sector not found error reading (or writing) drive x: 

[MS-DOS device error] 

e This error usually means the disk has a defective spot so that MS-DOS 
cannot find the requested information on it. 
You should copy all files from the disk onto a good disk and then try to 
reformat the defective disk. 
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Sector size too large in file filename 

[MS-DOS] 

e The specified device driver loaded by config.sys uses a sector size larger 
than that of any other device driver on the system. 
You cannot run this device driver. 


Seek error reading (or writing) drive x: 

[MS-DOS device error] 

e MS-DOS is unable to locate the information on the disk. 
Make sure that the disk is properly inserted in the drive, or try a different 
drive. 


SHARE already installed 
[Share] 
e Share can only be installed once. 


Sharing violation reading drive x: 

[MS-DOS device error] 

e A program tried to access a file that another program was currently using. 
Type A (for Abort), or wait awhile and type R (for Retry). 


SORT: Incorrect DOS version 
[Sort] 
e Sort does not run on MS-DOS versions before 2.0. 


SORT: Insufficient disk space 
[Sort] 
e The disk is full. 


SORT: Insufficient memory 
[Sort] 
e There is not enough memory to run the Sort program. 


Source and target drives are the same 
[Backup][Restore] 
e You specified the same drive for the source and target disks. 


Source disk is Non-removable 

{Backup} 

e This ts an informational message indicating that the source disk is a hard 
disk. 


Source does not contain backup files 

[Restore] 

e You are attempting to restore files froma disk that does not contain 
backup files. 
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Source Is a floppy (or hard) disk 
[Restore] 
e This is an informational message only. 


Source path required 
[Replace] 
e You did not specify a source path for the Replace command. 


Specified drive does not exist,or is non-removable 

[Diskcomp][Diskcopy] 

e You cannot compare or copy hard disks with this command. 
You must specify the name of a valid floppy drive. 


Specified MS-DOS search directory bad 
[MS-DOS] 
e = The Shell command in the config.sys file is incorrect. 
Make sure that the command.com file exists and that MS-DOS can find it. 


Strike a key when ready... 

[MS-DOS] 

e This prompt occurs during command processing and is always 
accompanied by another message. This message is also displayed if you 
have inserted a Pause command in a batch file. Usually, MS-DOS asks 
you to insert disks into appropriate drives before this prompt. 

To begin command processing, press any character, any number key, the 
SPACEBAR, OF the RETURN key. 


Syntax error 

[Attrib] [Find][MS-DOS] 

e You have entered a command incorrectly. 
Check to make sure you have typed the command correctly. Remember to 
enclose the find command string in double quotation marks. 


System transferred 


{Format][Sys] 
e The system files were transferred during Format or Sys command 
processing. 


Target cannot be used for backup 

[Backup] 

e Either the target disk has an unrecognizable format, or it is bad. 
Do not use the disk, or try to format the disk with the format command, or 
run chkdsk on it to determine the problem. 
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Target disk is Non-removable 


[Backup] 


e This is an informational message that the target disk is a hard disk. 


Target diskette is write protected 

[Diskcopy] 

e The target disk either has a write-protect tab on it, or it does not have a 
write-protect notch. 
If you want to destroy any existing information on the disk, remove the 
write-protect tab and give the command again. If the disk does not have a 
write-protect notch, you cannot use it as a target disk. 


Target diskette may be unusable 

[Diskcopy] 

e Either the target disk has an unrecognizable format, or it is bad. 
Try to format the disk with the format command, or mn chkdsk on it to 
determine the problem. 


Target is a floppy (or hard) disk 


[Backup] 
e = This is an informational message only. 


Target Is full 

[Restore] 

e There is no more room on the target disk for restored files. 
You must delete some of the files on the disk to make room for these files, 
or use another disk. 


Target is Non-Removable 
[Restore] 
e This is an informational message only. 


Terminate batch job (Y/N)? 

[MS-DOS] 

e Ifyou press controt-c while in batch mode, MS-DOS asks you whether or 
not you wish to end batch processing. 
Type Y (for Yes) to end processing, or type N (for No) to continue. 
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The current active keyboard table is xx with code page: yyy 

The current active CON code page is zzz 

[Keyb] 

e = This is an informational message that shows the current keyboard code, 
code page for the system and code page for the console (screen). 


The last file was not restored 


[Restore] 
e There was not enough room on the target disk for the file, or the last file 
was bad. 


Use the chkdsk command to determine the problem. 


The only bootable partition on drive 1 is already marked active 

[Fdisk] 

e You are trying to change the active partition. The active partition must 
reside on the first hard disk drive on your system and must be bootable. 
The only bootable partition on the first hard disk drive is already the 
active partition. 


Too many drive entries 

[Fastopen] 

e You can use Fastopen with up to four hard drives. You have tried to 
specify a fifth drive. 


Too many files open 

[Edlin][Label] 

e MS-DOS could not open the .bak file or write the volume label due to the 
lack of available system file handles. 
Increase the value of the files command in the config.sys file. 


Too many name entries 

[Fastopen] 

e The total number of entries specified for a drive exceeded the maximum of 
999. 


Too many open files 

[Backup][Fc][Restore][Xcopy} 

e MS-DOS could not open the files that you want to compare due to the lack 
of available system file handles. 
Increase the value of the files command in the config.sys file. 


Track 0 bad - disk unusable 

[Format] 

e The Format command can accommodate defective sectors on the disk, 
except for those near the beginning. 
You must use another disk. 
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Unable to create directory 

[Mkdir}[Xcopy] 

e MS-DOS could not create the directory you specified. 
Check to see that there is not a name conflict. You may have a file with 
the same name, or the disk may be full. 


Unable to create KEYB table in resident memory 

[Keyb] 

e MS-DOS tried to create a country-specific table for the keyboard code 
specified, but failed. 
Check the amount of available memory. There may not be enough 
memory available to create this table. 


Unable to erase 

[Backup] 

e Backup could not erase the files on the target disk. 
Check to see that the files on the backup disk are not read-only, and that 
the disk is not write-protected. 


Unable to shift Screen 
[Mode] 
© Mode is unable to shift the test pattern on the screen any farther. 


Unexpected DOS Error n 
[Replace] 
e An unexpected error n occurred, where n is the MS-DOS error number. 


Unrecognized command in CONFIG.SYS 

[MS-DOS] 

e = There is an invalid command in your config.sys file. 
Refer to Appendix B, "How to Configure Your System," for a list of valid 
statements. 


Unrecognized printer 

[Graphics] 

e You are using an invalid printer. 
Check to see whether you entered the command properly, or refer to 
Chapter 3, "MS-DOS Commands,” to make sure that you have specified a 
valid printer name. 


Unrecognized printer port 
[Graphics] 
© The printer device name that you specified was invalid. 
You may need to set the printer port by using the mode command. 
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Unrecoverable error in directory 
Convert directory to file (Y/N)? 


[Chkdsk] 
e This message is displayed if Chkdsk is unable to correct an error in a 
directory. 


If you respond Y (for Yes) to this prompt, chkdsk converts the bad 
directory into a file. You can then fix the directory or delete it. If you 
respond N (for No) to this prompt, you may not be able to write to or read 
from the bad directory. 


Unrecoverable read (or write) error on drive x: 

[MS-DOS device error] 

e MS-DOS is unable to read or write data to the specified device. 
Make sure that the disk is properly inserted in the disk drive. Then type R 
(for Retry). If the error occurs again, type A (for Abort). 


usage: fc [/a] [/b] [/c] [/l] [/Ib n] [/w] [t] [/n] [/NNNN] file1 file2 
[Fc] 
e One of the switches that you have specified is invalid. 


VERIFY Is off (or on) 
[MS-DOS] 
e This message tells you the current setting of the Verify command. 


nnn version of Graphic Character Set Table is already loaded 

[MS-DOS] 

e You tried to load the Graphic Character Set Table with the Graftabl 
command. This table already exists in memory. 


nnn version of Graphic Character Set Table is now loaded 
[Graftabl] 
o You have loaded the Graphic Character Set Table into memory. 


Volume In drive x: has no label 

[Dir][Label][Vol] 

e This is an informational message displayed in response to the Dir, Label, 
or Vol command. 


Volume in drive x: is filename 

[Dir] [Label][Vol] 

e = This is an informational message displayed in response to the Dir, Label, 
or Vol command. 
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Volume label (11 characters, ENTER for none)? 

[Format][Label] 

e This message is displayed when you specify the Label commana, or the |v 
switch in the Format command. 
Type a volume label, or press the RETURN key to indicate that you do not 
want a volume label for this disk. It’s a good idea, though, to specify a 
volume label to help you identify your disks. 


WARNING, ALL DATA ON NON-REMOVABLE DISK 

DRIVE x: WILL BE LOST! 

Proceed with Format (Y/N)? 

[Format] 

e This message appears when you try to format a hard disk that already 
contains data. 
If you type Y (for Yes) the data on the disk will be erased. If you do not 
want the files on your hard disk erased, type N (for No). Copy the files to a 
floppy disk and repeat the format command. 


Warning! Date in the extended DOS partition could be 

destroyed. 

Do you wish to continue.......? [n] 

[Fdisk] 

e You are trying to delete an extended DOS partition. 
Be sure this is what you want to do. If you do want to delete the extended 
DOS partition specified, type Y (for Yes) and press rETurN. If not, the 
default response N is already typed. Press RETURN. 


Warning! Date in the primary DOS partition could be 

destroyed. 

Do you wish to continue....... ? [n] 

[Fdisk] 

e You are trying to delete the primary DOS partition. 
If you are sure you want to delete your primary DOS partition, type Y and 
press RETURN. If not, press RETURN; MS-DOS will not delete the partition. 


Warning - directory full 

[Recover] 

e The root directory is too full for Recover processing. 
Delete some files in the root directory to free space for the recovered files, 
and try the command again. 
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Warning! Diskette is out of sequence 

Replace diskette or continue if okay 

Strike any key when ready 

[Restore] 

e You should restore the diskettes in the order that you backed them up. 


Warning! File filename 
is a hidden (or read-only) file 
Replace the file (Y/N)? 


[Restore] 
e This message prompts you as to whether you want to replace a hidden or 
read only file. 


Type Y (for Yes) if you want to restore the hidden or read-only file from 
the backup disk. Type N (for No) if you do not want to restore this file. 


Warning! File filename 
was changed after it was backed up 
Replace the file (Y/N)? 


[Restore] 

e This message prompts you as to whether you want to replace a backup file 
that has been changed. 
Type Y (for Yes) if you want to restore this file, or type N (for No) if you 
do not. 


Warning! Files in the target drive 

BACKUP (or root) directory will be erased 

[Backup] 

e Backup found files in the target drive, and you did not specify the /a switch 
to append files. 


Warning! No files were found to back up 
[Backup] 
e Backup did not find any files to back up on the disk you specified. 


Warning! No files were found to restore 

[Restore] 

e Restore did not find the file that you wanted to restore from the backup 
disk. 


Warning: Read error in EXE file 

[Exe2bin] 

e The amount read was less than the size of the header. This is a warning 
message only. 
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Warning! The partition marked active is not bootable 
[Fdisk] 
e The active DOS partition must be bootable. 


Write fault error writing drive x: 

[MS-DOS device error] 

e MS-DOS is unable to write data to the specified device. 
Make sure that the disk is properly inserted in the disk drive. Then type R 
(for Retry). If the error occurs again, type A (for Abort). 


Write protect error writing drive x: 

[MS-DOS device error] 

e You tried to write data on a write-protected disk. 
If the disk has a write-protect tab on it, you must remove the tab before 
you can write on the disk. (You should consider first why the disk was 
write-protected.) If the disk doesn’t have a write-protect notch, you cannot 
write on that disk. 


Index 


> prompt 3.81 

< prompt 3.81 

$ prompt 3.81 

.bak extension 6.3, 6.26 

.bat extension 2.2,4.1,4.7 

.com extension 2.2, 8.2 

.doc extension 3.32, 3.84 

-exe extension 2.2 

.exe file 2.2, 7.1, 8.2, 8.20 

lib extension 7.3 

.map extension 7.3 

.obj extension 7.2 

.ref extension 3.32 

.txt extension 1.9, 1.10, 3.32, 3.84 

/cparmaxalloc option, abbreviation 
7.19 

/cparmaxalloc option, link 7.18 

/dosseg option, abbreviation 7.23 

/dosseg option, link 7.22 

/dsallocate option, abbreviation 7.20 

/dsallocate option, link 7.11, 7.20 

/exepack option, link 7.14 

/help option, abbreviation 7.13 

help option, link 7.13 

/high option, abbreviation 7.19 

Migh option, link 7.11, 7.19 

/flinenumbers option, abbreviation 
7.16 

/flinenumbers option, link 7.5, 7.15 

/map option, abbreviation 7.15 

/map option, link 7.5, 7.10, 7.15 

/nodefaultlibrary option, 
abbreviation 7.17 


/nodefaultlibrarysearch option, link 
7.17 
/nogroupassociation option, link 
7.20 
/noignorecase option, abbreviation 
7.17 
/moignorecase option, link 7.16 
/overlay interrupt option, 
abbreviation 7.21 
/overlayinterrupt option, link 7.21 
/pause option, abbreviation 7.13 
/pause option, link 7.13 
/segments option, abbreviation 7.22 
/segments option, link 7.22 
/stack option, abbreviation 7.18 
/stack option, link 7.17 
Abbreviation 
/cparmaxalloc option, link 7.19 
/dosseg option, link 7.23 
/dsallocate option, link 7.20 
help option, link 7.13 
high option, link 7.19 
flinenumbers option, link 7.16 
/map option, link 7.15 
/nodefaultlibrarysearch option, 
link 7.17 
/noignorecase option, link 7.17 
/overlayinterrupt option, link 7.21 
/pause option, link 7.13 
/segments option, link 7.22 
/stack option, link 7.18 
debug memory locations 
BYTE 8.7 
WORD 8.7 
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Aborting a command 5.7 
Adding lines, Edlin 6.14 
Adding spacing to batch files 4.20 
Align type, link 7.24 
Allocating a data group, link 7.20 
Allocating disk space 1.2, 3.42 
Alphabetical sorting 2.5, 4.9 
Alphabetizing a file 3.96 
ANSI escape sequence 

CUB C.3 

CUD C.3 

CUF C.3 

CUU C3 

definition C.2 

DSR C.3 

ED C.4 

EL C.4 

modes of operation C.4 

RCP C.3 

RM C.5 

SCP C.3 

SGR C.4 

using in config.sys file B.7 
ANSI escape sequence, driver 3.82 
ANSI.SYS C.1 
Append command 

purpose 3.9 

syntax 3.9 
Append command, Edlin 

purpose 6.14 

syntax 6.14 
Appending output 2.4 
Argument 3.4 
ASCII characters 8.10 
ASCII code (escape) prompt 3.81 
ASCII file 3.30 
Assemble command, debug 

abbreviation 8.7 

comments 8.7 

purpose 8.7 

syntax 8.7 
Assign command 

purpose 3.11 

syntax 3.11 


Asterisk (*) 
as system prompt in Edlin 6.2 
wildcard character 1.9 
Asynchronous communications 
mode 3.69 
Attnb command 
purpose 3.13 
syntax 3.13 
Attribute, setting 3.13 
Autoexec.bat file 2.4, 3.34, 4.3, 4.6 
BASIC 4.6 
clearing the screen 4.6 
Date 4.6 
default directory 4.6 
default drive 4.6 
detaching swapper 4.6 
Path 4.6 
prompt 4.6 
size of memory partitions 4.6 
Time 4.6 


Background color functions, ANSI 
C.4 
Backslash (\) 1.7 
Backup command 
code pages E.4 
ERRORLEVEL 3.89 
purpose 3.15 
switch 
/a 3.15 
/d 3.15 
/L3.16 
/m 3.15 
Is 3.15 
{3.15 
syntax 3.15 
Backup disk 1.2 
Bad call format error F.4 
Bad command error F.4 
Bad sectors 3.83 
Bad unit error F.5 
Bar, vertical, See Pipe symbol ( ; ) 
BASIC 4.6 


Batch command 
Call 4.12 
Echo 4.13 
For 4.14 
Goto 4.16 
If 4.17 
Pause 4.19 
Rem 4.20 
Shift 4.21 
Batch file 
chain 4.3 
checknew. bat 4.12 
comment 4.20 
creating 4.1 
definition 4.1 
dividing into pieces 4.19 
label 4.16 
nesting 4.12 
processing 3.93 
readability and spacing 4.20 
remark 4.20 
replaceable parameters 4.7 
running 4.2, 4.9 
sorter.bat 4.7, 4.9 
stopping 4.19 
suspending execution of 4.19 
using a colon in 4.16 
using a percent sign in 4.8, 4.15 
using redirection symbols in 4.3 
using temporary files with 4.10 
using the shift command with 
4.21 
Batch processing 3.93, 4.1, 4.14 
Batch processing commands 4.11 
Batch program, halting 4.19 
Batchfile, placeholder 4.12 
Baud rate 3.70 
Bin directory 1.6, 2.3 
Binary file 
copying 3.30 
displaying 3.103 
BKSP key 6.4 
Blink function, ANSI C.4 
Block of text, moving, Edlin 6.23 


Index 3 


Bold function, ANSI C.4 
Brackets, used for options 3.5 
Break command 
purpose 3.18 
syntax 3.18 
Break command, config.sys file 
definition B.2 
purpose B.2 
syntax B.2 
Buffer space, fc 3.49 
Buffer, intemal 3.78 
Buffers command, config.sys file 
definition B.2 
purpose B.5 
syntax B.5 
Byte 8.5 
Bytes, available 3.23 


Call command, batch 
purpose 4.12 
syntax 4.12 
Capital letter, use of 6.22 
Case-sensitivity, preserving 7.16 
Chains, batch file 4.3 
Changing directories 1.11 
Changing the name of a file 3.84 
Chcp command 
code pages E.3 
Chdir command 
changing the working directory 
1.11 
purpose 3.21 
shorthand notation 1.12 
syntax 3.21 
Checknew. bat file 4.12 
Chckdsk command 
checking files for errors 1.3 
errors found 1.3 
purpose 3.23 
status report 1.3, 3.23 
switch 
/f 3.23 
lv 3.23 
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Chckdsk command (continued) 
syntax 3.23 
Class type, link 7.24 
Clearing the screen 3.25 
Cls command 
purpose 3.25 
syntax 3.25 
Code pages E.1 
console screen 3.71, E.6 
default E.1 
definition E.1 
displaying current status 3.72 
displaying status E.3 
Mode command 3.71, E.3 
parallel printer 3.71 
preparing 3.72, E.3 
refreshing E.3 
refreshing settings 3.72, E.9 
selecting 3.72, E.3 
Colon, using in a batch file 4.16 
COM1, communications port 3.70 
COM2, communications port 3.70 
Combine type, link 
at 7.25 
common 7.25 
memory 7.25 
private 7.25 
public 7.25 
stack 7.25 
Combining files 3.32 
Combining segments 7.25 
Command 
Append 3.9 
Assign 3.11 
Assign. See also Subst 
Attnb 3.13 
Backup 3.15, 3.89, E.4 
batch processing 4.11 
Break, config.sys file 3.18, B.2, 
B.4 
Buffers, config.sys file B.2, B.5 
Call 4.12 
Cd 1.11 
Chep E.3 


Chdir 3.21 
Chkdsk 1.3, 3.23 
checking files for errors 1.3 
errors found 1.3 
status report 1.3 
Cls 3.23 
Command 3.24 
commands not usable over 
network 
Chkdsk 3.2 
Diskcomp 3.2 
Diskcopy 3.2 
Format 3.2 
Label 3.2 
Recover 3.2 
Subst 3.2 
Sys 3.2 
conditional execution 4.17 
Copy 3.30 
Country, config.sys file B.2 
Date 3.34, E.4 
Debug commands 8.4 
default value 3.4 
Del 1.10, 2.2, 3.36 
Device, config.sys file B.2, B.7 
Dir 1.7, 1.12, 2.2, 3.37 
Diskcomp 3.39 
Diskcopy 2.2, 3.42 
Drivpamn, config.sys file B.2 
Echo 4.13 
Exe2bin 3.44 
Exit 3.46 
extemal 2.1, 2.2, 2.3, 3.2 
Fastopen 3.47 
Fc 3.48 
FCBS, config.sys file B.2, B.10 
Fdisk 3.51 
Files, config.sys file B.2, B.11 
Find 2.5, 3.52 
For 4.14 
Format 1.3, 2.2, 3.56 
format.bat 2.2 
Goto 4.16 
Graftabl 3.58 


Command (continued) 

Graphics 3.60 

If 4.17 

internal 2.1, 3.2 

Join 3.62 

Keyb E.3, E.6 

Keybdv 3.64 

Keybfr 3.64 

Keybgr 3.64 

Keybit 3.64 

Keybsp 3.64 

Keybuk 3.64 

Label 3.66 

list of 2.6 

Mkdir 1.11, 3.68 

Mode 3.69, E.3 

More 2.5, 3.74 

Nlsfunc 3.76, E.3, E.6 

Path 2.3, 3.77 

Pause 4.19 

pipeline 2.6 

piping 2.5 

Print 3.78 

Prompt 3.81 

Recover 3.83 

Rem 4.20 

Ren 3.84 

repeating 4.23 

Replace 3.85 

Restore 3.88, E.4 

Rmdir 1.12, 3.90 

rules for using options 
brackets 3.5 
ellipsis 3.5 
equal sign 3.5 
italic 3.5 
semicolon 3.5 
spaces and tabs 3.5 

Select 3.91, E.3 

Set 3.93 

Share 3.95 

Shell, config.sys file B.2, B.13 

Shift 4.21 

Sort 2.5, 3.96 
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Command (continued) 
Subst 3.98 
symbol 
extemal 3.2 
internal 3.2 
non-network 3.2 
syntax 3.4 
Sys 3.99 
Time 3.100, E.4 
Tree 3.102 
Type 2.2, 3.103 
Ver 3.104 
Verify 3.105 
Vol 3.106 
Xcopy 3.107 
Command command 
purpose 3.26 
switch 
/c 3.26 
|p 3.26 
syntax 3.26 
Command information, argument 
3.4 
Command line 
parameters, changing position of 
4.21 
relation to template 5.2 
Command lines with link 7.4 
Command options, Edlin 6.12 
Command parameter, debug 
address 8.5 
byte 8.5 
description 8.4 
drive: 8.5 
list 8.6 
range 8.5 
record 8.5 
string 8.6 
value 8.5 
Command processor, MS-DOS 
3.26, 3.46 
Command.com 2.1, 4.17, B.2, B.3 
exiting 3.46 
Comment, batch file 4.20 
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Communications port 
COM1 3.70 
COM2 3.70 
Compare command, debug 
abbreviation 8.9 
comments 8.9 
purpose 8.9 
syntax 8.9 
Comparing files 3.48 
Compilers 7.15 
overlays 7.5, 7.21 
Computer memory 2.1 
Computer network 3.2 
Concatenation 3.32 
Concealed function, ANSI C.4 
Condition parameter 4.17 
Conditional execution of commands 
4.17 
Config.sys command 
Break B.2, B.4 
Buffers B.2, B.5 
Country B.2, B.6, E.4, E.5 
Device B.2, B.7, E.4 
Drivpann B.2 
FCBS B.2, B.10 
Files B.2, B.11 
Shell B.2, B.13 
Config.sys file B.1, B.2 
Configuration File See Config.sys 
file 
Configuring a hard disk 3.51 
Configuring your system B.1 
Console 4.2 
Console screen 
code page switching 3.71, E.6 
Console screen code pages, 
selecting E.8 
Control-character functions 5.6 
CONTROL key sequence 
stop a command, CONTROL-C 5.6 
stop screen scrolling, CONTROL-S 
5.6 
CONTROL-ALT-F1 3.64 
CONTROL-ALT-F2 3.64 


CONTROL-BREAK 3.70 
CONTROL-C 3.112, 4.19, 5.6, 5.7, 
6.11, 6.20, 8.1, B.4 
CONTROL-C check 3.18, B.4 
CONTROL-H 5.7 
CONTROL-J 5.7 
CONTROL-N’5.7 
CONTROL-P 5.7 
CONTROL-S 5.6, 5.7, 8.1 
CONTROL-Y 6.11 
CONTROL-X 5.7 
CONTROL-Z 3.31, 4.2, 4.6, 4.7, 6.27 
Copy command 
purpose 3.30 
switch 
/a 3.30 
[b 3.30 
Iv 3.30 
syntax 3.30 
using wildcard with 3.32 
Copy command, Edlin 
purpose 6.15 
syntax 6.15 
Copying 
disks 3.42 
File Allocation Table 1.3 
files 3.30 
lines, Edlin 6.15 
template characters 5.6 
Country command, config.sys file 
changing time format 3.100 
code pages E.4 
country-specific E.4 
definition B.2 
purpose B.6 
syntax B.6 
Creating a directory 1.11, 3.68 
CUB-Cursor Backward, ANSI 
escape sequence C.3 
CUD-Cursor Down, ANSI escape 
sequence C.3 
CUF-Cursor Forward, ANSI escape 
sequence C.3 


CUP-Cursor Position, ANSI escape 
sequence C.3 

Cursor 
in the template 5.4 
location, Edlin 6.5, 6.6, 6.7, 6.8 
movement C.2 

CUU-Cursor Up, ANSI escape 
sequence C.3 


Data group, allocating in link 7.20 
Data path, NUL 3.9 
Data, losing F.1 
Databit 3.70 
Date command 
code pages E.4 
purpose 3.34 
syntax 3.34 
Date format, country-specific E.5 
Date message 3.35 
Date prompt 3.81 
Debug 
arglist 8.3 
command parameters 
address 8.5 
byte 8.5 
description 8.4 
drive: 8.5 
list 8.6 
range 8.5 
record 8.5 
string 8.6 
value 8.5 
commands 8.4 
error indication 8.3 
error messages 8.34 
hyphen prompt 8.2 
illegal ranges 8.6 
illegal strings 8.6 
memory locations, abbreviating 
8.7 
mnemonics 8.7 
opcodes 8.8 
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Debug (continued) 
quitting 8.25 
starting 8.2 


Debug command 

assemble 8.7 

compare 8.9 

dump 8.10 

enter 8.12 

fill 8.14 

go 8.15 

hex 8.17 

input 8.18 

load 8.19 

move 8.21 

name 8.22 

output 8.24 

quit 8.25 

register 8.26 

search 8.29 

trace 8.30 

unassemble 8.31 

write 8.33 
Debug errors 

BF - Bad flag 8.34 

BP - Too many breakpoints 8.34 

BR - Bad register 8.34 

DF - Double flag 8.34 
Debugging programs 8.1 
Default code page, United States 

E.1 
Default drive 3.4, A.1 
Default drive prompt 3.81 
Default filename extension, link 7.2 
Default libraries, ignoring 7.17 
Default printer, PRN 3.78 
Default value, commands 3.4 
Del command 1.10 

purpose 3.36 

syntax 3.36 
DEL command, Edlin 

purpose 6.4 

similarity to F1 6.4 

syntax 6.4 
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DEL key 5.2, 6.4 
Delete command, Edlin 
purpose 6.16 
syntax 6.16 
Deleting 
a directory 1.12, 3.90 
files 1.13, 3.36 
lines, Edlin 6.16 
template characters 5.6 
text, Edlin 6.1 
Device command, config.sys file 
code pages E.4 
definition B.2 
purpose B.7 
syntax B.7 
Device error F.1 
Device, operation mode 3.69 
Difference reporting, (Fc) 3.49 
Dir command 
purpose 3.37 
syntax 3.37 
using wildcards with 3.37 
Directives, link 7.23 
Directory 
bin 2.3 
changing 1.11, 3.21 
creating 1.11 
deleting 1.12 
displaying 1.12, 3.37 
erasing 1.12 
external commands, bin 1.6 
hierarchical structure 1.4, 1.5 
listing of 1.7 
making 3.68 
maximum capacity 1.4 
multilevel 1.3, 1.4, 1.5, 1.7 
removing 1.12, 3.90 
renaming 1.13 
root 1.3, 1.15, 3.62 
shorthand notation 1.7 
sorted listing 3.97 
sorting 2.6 
subdirectones 1.4, 1.5, 1.6, 1.12 
system 1.5 


Directory (continued) 
user 1.6 


working 1.5, 1.11, 2.3, 3.9 


Disk 
backing up 3.15 
checking 3.23 
copying 3.42 
formatting 3.52 
fragmented 3.42 
media 3.15, 3.88 
sector 3.83 
types 3.15, 3.88 
volume label 3.106 
write-protected 3.74 
writing to 3.105 
Disk buffer 
default number of B.5 
definition B.5 
Disk drive B.4 
if you have only one 3.6, A.1 
source 3.4 
target 3.4 
virtual 3.98 
Disk error F.1 
Disk space, allocation of 3.42 
Disk swapping 7.13 
Diskcomp command 
purpose 3.39 
syntax 3.39 
Diskcopy command 
option 
source drive 3.42 
target drive 3.42 
purpose 3.42 
syntax 3.42 
Display modes 3.69 
Display.sys file 
code pages E.4 
country-specific E.4 
Displaying a command, MS-DOS 
4.13 
Displaying a directory 3.37 


Displaying a file 2.5, 3.103 
Displaying lines, Edlin 6.22 
Dividing a batch file into pieces 
4.19 
Drive 
source 3.4 
target 3.4 
Drive letter 3.98, 3.106 
Drive name E.4 
Driver.sys C.1 
Drivparm command, config.sys file 
B.2, B.8 
DSR-Device Status Repon, ANSI 
escape sequence C.3 
Dummy parameter. See Replaceable 
parameter 
Dump command, debug 
abbreviation 8.10 
comments 8.10 
purpose 8.10 
syntax 8.10 


Echo command, batch 
purpose 4.13 
syntax 4.13 

Echoing a command, See 

Displaying a command, 
MS-DOS 

ED-Erase Display, ANSI escape 
sequence C.4 

Edit command, Edlin 
purpose 6.17 
syntax 6.17 

Editing a file 6.1 

Editing commands 
copy multiple characters 6.5 
copy one character 6.5 
copy template 6.6 
enter insert mode 6.8 
new template 6.8 
quit 6.7 
skip multiple characters 6.6 
skip one character 6.6 
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Editing key 


DEL 5.3 
description 6.4 
Esc 5.3 

F 5.2 

F2 5.2 

F3 5.2 

F4 5.3 

F5 5.3 

F6 5.3 

Ins 5.3 


Editing text, Edlin 6.17 
Edlin 


.bak extensions 6.3 
adding lines 6.14 
adjusting lines 6.2 
asterisk (*) prompt 6.2 
changing your config.sys file 
with B.1 
command Option 
line 6.12 
question mark 6.13 
text 6.13 
consecutive line numbering 6.2 
copying lines 6.15 
creating a new file 6.2 
current line, asterisk (*) 6.10 
cursor location 6.5, 6.6, 6.7, 6.8 
default values 6.22 
deleting lines 6.1, 6.16 
displaying lines 6.1 
editing an existing file 6.3 
editing text 6.1, 6.17 
freeing memory 6.3 
insert mode 6.5, 6.6, 6.7, 6.8 
inserting text 6.1, 6.20 
line numbers 6.2 
listing text 6.22 
loading files into memory 6.3, 
6.33 
memory capacity 6.33 
merging files 6.32 
moving lines 6.23 
omitting options 6.22 
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Edlin (continued) 
paging through files 6.25 
question mark option 6.30 
quitting 6.3, 6.26 
renumbering lines 6.2 
replace mode 6.8 
replacing text 6.27 
revising 6.1 
saving a file 6.3, 6.19 
searching for text 6.30 
Starting 6.2 
using commands with 6.10 
wniting to a disk 6.33 
Edlin command 
Append lines 6.14 
Copy lines 6.15 
Delete lines 6.16 
Edit line 6.17 
End editing 6.19 
Insert text 6.20 
List text 6.22 
listing of 6.10 
Move text 6.23 
Page 6.25 
Quit 6.26 
Replace text 6.26 
Search text 6.30 
Transfer text 6.32 
Write lines 6.33 
EL-Erase Line, ANSI escape 
sequence C.4 
Ellipsis, used for options 3.5 
End-of-file mark 3.31 
Ending an edit session, Edlin 6.19 
Enter command, debug 
abbreviation 8.12 
comments 8.12 
purpose 8.12 
syntax 8.12 
Environment strings 4.3 
Environment variable 
LIB 7.9 
Environment, definition 3.93 
Equal sign, used for options 3.5 


Erase command 3.36 
Erasing 
files 1.13 
the screen C.4 
Error checking 
directories 1.3 
disks 1.3 
File Allocation Table 1.3 
files 1.3 
Error indication, debug 8.3 
Error message 
action F.1 
device F.1 
disk F.1 
type F.1 
Debug 8.34 
MS-DOS F.1 
network 3.2 
Error 
recovering from F.2 
responding to F.2 
ESC key 5.2, 6.4 
ESC command, Edlin 
purpose 6.7 
similarity to F5 6.7 
syntax 6.7 
Escape sequence, ANSI 3.82, B.7, 
C.2,C.4 
Example config.sys file B.2 
Exe2bin command 
purpose 3.44 
syntax 3.44 
Executable file, creating 7.1 
Executable file packing, link 7.14 
Executable file, .exe 2.2 
Executable image 7.23 
Executable program, link 7.4 
Executing a .bat file 4.9 
Exit code 4.17 
Exit command 
purpose 3.46 
syntax 3.46 
Extension 
-bak 6.3, 6.26 


Extension (continued) 
-bat 2.2, 4.1, 4.7 
.com 2.2, 8.2 
.doc 3.32, 3.84 
exe 2.2, 7.2, 8.2, 8.20 
lib 7.3 
map 7.3 
.obj 7.2 
ef 3.32 
txt 1.9, 1.10, 3.32, 3.84 
substitution 3.32 
External command 
bin directory 1.6 
definition 2.2 
searching for 3.77 
symbol 3.2 


Fi key 5.2, 6.4 

F1 command, Edlin 
purpose 6.5 
similarity to DEL 6.5 
syntax 6.5 

F2 key 5.2, 6.4 

F2 command, Edlin 
purpose 6.5 
similarity to F4 6.5 
syntax 6.5 

F3 key 5.2, 6.4 

F3 command, Edlin 
purpose 6.6 
syntax 6.6 

F4 key, 5.2, 6.4 

F4 command, Edlin 
purpose 6.6 
similarity to F2 6.7 
syntax 6.6 

F5 key 5.2, 6.4 

F5 command, Edlin 
purpose 6.8 
similarity to ESC 6.8 
syntax 6.8 

F6 key 5.2 

Faint function, ANSI C.4 
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Fastopen command 
purpose 3.47 
syntax 3.47 
FAT. See File Allocation Table 
Fc 3.48 
purpose 3.48 
switches 3.48 
syntax 3.48 
FCBS command, config.sys file 
definition B.2 
purpose B.10 
syntax B.10 
Fdisk command 
menus 3.51, D.1 
purpose 3.51 
syntax 3.51 
File 
alphabetizing 3.96 
ASCII 3.30 
attribute 3.13 
autoexec.bat 2.4, 3.34, 4.3, 4.6 
backup 6.26 
backup.log 3.16 
batch 3.93, 4.7 
binary 3.30 
command.com 2.21 
concatenating 3.32 
config.sys 3.100, B.1, E.4 
copying 3.30 
creating a new file, Edlin 6.2 
deleting 3.36 
deleting a temporary file 4.10 
display.sys E.4 
displaying 2.5, 3.103 
editing 6.1 
editing an existing file, Edlin 6.3 
grouping 1.4 
hidden 3.23, 3.88 
location of 1.2 
organization 1.3, 1.7 
printer.sys E.4 
printing 3.78 
protection 1.2 
read-only 3.88 
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File (continued) 
recovery 3.83 
renaming 3.84 
searching for 1.5 
separation by category 1.3 
sorter.bat 4.7 
sorting 2.5, 3.96 
system 1.4 
temporary 3.74, 4.7, 4.10 
text 6.1 
updating 6.1 
File Allocation Table 
allocating disk space 1.2 
copying of 1.2 
definition 1.2 
locating files 1.2 
File Control Blocks. See FCBS 
File header, MS-DOS 7.12 
File restoring 3.88 
Filename 
as a command option 3.4 
autoexec.bat 2.4 
command.com 2.1 
syntax 3.4 
Filename extension 
-bat 2.2 
com 2.2 
exe 2.2, 7.2 
lib 7.3 
map 7.3 
xt 1.9, 1.10 
when to add 2.3 
Files, comparing 3.48 
Files command, config.sys file 
definition B.2 
purpose B.11 
syntax B.11 
Fill command debug 
abbreviation 8.14 
comments 8.14 
purpose 8.14 
syntax 8.14 


Filter 
definition 2.5 
Find 2.5 
More 2.5, 3.74 
Sort 2.5, 3.97 
Find command 
purpose 3.52 
switch 
Ic 3.52 
h 3.52 
Iv 3.52 
syntax 3.52 
Finding a file 1.5 
Fixups, link 7.26 
Flags 8.27 
Floppy disk drive, if you have only 
one A.1 
For command, batch 
purpose 4.14 
syntax 4.14 
Foreground color functions, ANSI 
C.4 
Format command 
purpose 3.54 
switch 
lv 3.55 
syntax 3.54 
Formatting a disk 3.54 
Fragmented disk 3.42 
Frame number, canonical 7.24 
Freeing memory, Edlin 6.3 
Function key 
DEL 5.3 
descnption 6.4 
ESC 5.3 
F1 5.2 
F2 5.2 
F3 5.2 
F4 5.2 
F5 5.3 
F6 5.3 
Ns 5.3 
Functions, special editing 5.2 


General failure error F.27 
Go command, debug 
comments 8.15 
purpose 8.15 
syntax 8.15 
Goto command, batch 
purpose 4.16 
syntax 4.16 
Graftabl command 
purpose 3.58 
syntax 3.58 
Graphic functions, changing C.2 
Graphics command 
purpose 3.60 
syntax 3.60 
Graphics monitor 
color disabled (BW) 3.71 
color enabled (CO) 3.71 
Graphics, ANSI escape sequences 
function C.4 
Background colors C.4 
Blink C.4 
Bold C.4 
Concealed C.4 
Faint C.4 
Foreground colors C.4 
Italic C.4 
Reverse Video C.4 
parameter C.4 
Set Graphics Rendition-SGR C.4 
Grouping files 1.4 
Groups, linking 7.26 


Halting a command 5.7 
Hard disk configuration 3.51 
Hex command, debug 
abbreviation 8.17 
comments 8.17 
purpose 8.17 
syntax 8.17 
Hidden file 3.23, 3.88, 3.9 
restoring 3.88 
removing 3.90 


Index 13 


Hierarchical directory, definition 
1.4, 1.6 

High start address, setting 7.19 

Hint, autoexec.bat 4.4 

HVP-Horizontal and Vertical 
Position, ANSI excape sequence 
C3 

Hyphen prompt, debug 8.2 


If command, batch 
purpose 4.17 
syntax 4.17 
legal range, debug 8.6 
Tegal string, debug 8.6 
Input 2.4 
Input command, debug 
abbreviation 8.18 
comments 8.18 
purpose 8.18 
syntax 8.18 
Input, redirecting 2.5 
INS key 5.2, 6.4 
INS command, Edlin 
purpose 6.8 
syntax 6.8 
Insert command, Edlin 
purpose 6.20 
syntax 6.20 
Insert mode, Edlin 6.5, 6.6, 6.7, 6.8 
Inserting template characters 5.6 
Inserting text, Edlin 6.1, 6.20 
Interactive processing 4.14 
Internal buffer 3.78 
intemal command 2.1 
definition 2.1 
symbol 3.2 
syntax. See Command syntax 
Intemational 
case conversion B.6 
currency B.6 
date B.6 
time B.6 
Invalid disk change error F.34 
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Inverse video mode 3.82 
Italic function, ANSI C.4 
Italics, used for options 3.5 
Join command 

purpose 3.62 

syntax 3.62 
Joining files 3.32 


Key 
DEL 5.3 
editing 5.1 
Esc 5.3 
Fi 5.2 
F2 5.2 
F3 5.2 
F4 5.3 
F5 5.3 
F6 5.3 
INS 5.3 
LINEFEED 5.7 
reassigning C.2 
template 5.1 
Key sequence 
CONTROL-BREAK 3.70 
CONTROL-C 5.7, 6.11, 6.20, B.4 
CONTROL-H 5.7 
CONTROL J 5.7 
CONTROL-N 5.7 
CONTROL-P 5.7 
CONTROL-S 5.7 
CONTROL-V 6.11 
CONTROL-X 5.7 
CONTROL-Z 3.70, 6.27 
Keyb command 3.64 
code pages E.3 
purpose 3.64 
syntax 3.64 
Keyboard 
copying information from 4.2 
type 3.64 
Keyboard code E.6 


Label command 3.66 
purpose 3.66 
syntax 3.66 
Label variable, batch 4.16 
Letters, lowercase 8.3 
Letters, uppercase 8.3 
LIB environment variable 7.9 
Library file 7.3, 7.5 
Line editor, Edlin 1.11, 4.1, 6.1 
Line mode C.5 
Line option, Edlin 
description 6.12 
number 6.12 
number sign 6.12 
period 6.12 
Line parameter C.2 
LINEFEED key 5.7 
Lineprinter, output to 5.7 
Link 
align type 7.24 
canonical frame number 7.24 
class type 7.24 
command line 7.4 
creating an executable file 7.4 
default extension 7.2 
description 7.1 
directive 7.23 
frame number, canonical 7.24 
group 7.26 
library file 7.3, 7.5 
library search 7.17 
map file 7.3, 7.4, 7.10, 7.15 
operation 7.23 
option 
/cparmaxalloc 7.18 
/dosseg 7.22 
/dsallocate 7.11, 7.20 
/exepack 7.14 
help 2.13 
high 7.11, 7.19 
finenumbers 7.15 
/map 7.5, 7.10, 7.15 
/nodefaultlibrarysearch 7.17 


option (continued) 
/nogroupassociation 7.20 
/noignorecase 7.16 
/overlayinterrupt 7.21 
/pause 7.13 
/segments 7.22 
{stack 7.17 
overlay 7.5, 7.21 
placeholder 7.4 
preserving case-sensitivity 7.16 
prompt 7.2 
references 
long 7.26 
near segment-relative 7.26 
near self-relative 7.26 
short 7.26 
response file 7.7 
search path 7.9 
starting 7.2 
temporary file 7.11 
using the comma with 7.3 
using the semicolon with 7.3 
variable 
executable file 7.6 
libraryfiles 7.5 
mapfile 7.5 
objectfiles 7.6 
Linking, described 7.1, 7.23 
List command, Edlin 
purpose 6.22 
syntax 6.22 
Listing a directory 1.7 
Listing lines, Edlin 6.22 
Load command, debug 
abbreviation 8.19 
comments 8.19 
purpose 8.19 
syntax 8.19 
Locating a file 1.2, 1.5 
Long reference, link 7.27 
Lowercase letters 8.3 
Lowercase letters, preserving 7.16 
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Making a directory 11, 1.11, 3.68 
Map file 
addresses 7.10 
creating 7.3, 7.15 
format 7.4 
including line numbers 7.15 
including public symbols 7.10 
segments 7.10 
Maximum memory allocation, 
controlling in link 7.18 
Media, disk 
floppy 3.15, 3.88 
hard 3.15, 3.88 
Memory 
allocating disk buffers B.5 
computer 2.1 
MENU, BASIC 4.6 
Merging files, Edlin 6.32 
Message directory F.1! 
Message, placeholder 4.13 
Misspelling, template 5.5 
Mistakes, correcting 5.1 
Mkdir command 
purpose 3.68 
syntax 3.68 
working directory 3.68 
Mnemonics, debug 8.7 
Mode 
asynchronous communications 
3.69 
code page switching 3.71 
console-screen code pages 3.71, 
E.3 
device code pages 3.71 
display 3.69 
inverse video 3.82 
operation 3.69 
parallel printer 3.69 
parallel printer code pages 3.71, 
E.3 
Mode command 
asynchronous communications 
mode, default settings 3.70 
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Mode command (continued) 
asynchronous communications 
mode, options 3.70 
code pages E.3 
display modes, options 3.71 
parallel printer mode 
default settings 3.70 
options 3.70 
purpose 3.69 
syntax 3.69 
Modes of operation C.4 
Monochrome display adapter 3.71 
More command 
purpose 3.74 
syntax 3.74 
Move command, debug 
abbreviation 8.21 
comments 8.21 
purpose 8.21 
syntax 8.21 
Move command, Edlin 
purpose 6.23 
syntax 6.23 
Moving lines, Edlin 6.23 
MS-DOS 
argument 3.4 
command processor 3.26, 3.46 
exiting to from Edlin 6.26 
file header 7.12 
function keys 5.1 
line editor, Edlin 4.1 
special editing keys 5.1 
special prompt 3.81 
switches 3.4 
MS-DOS command 
Append 3.9 
Assign 3.11 
Attnb 3.13 
Backup 3.15, 3.89 
Break 3.18 
Call 4.2 
Chdir 1.11, 3.21 
Chkdsk 1.3, 3.23 


MS-DOS command (continued) 
Cls 3.25 
Command 3.26 
Copy 2.2, 3.30 
Date 3.34 
Del 2.2, 3.36 
Dir 1.7, 1.12, 2.2, 3.7 
Diskcomp 3.39 
Diskcopy 2.2, 3.42 
Echo 4.13 
Exe2bin 3.44 
Exit 3.46 
extemal 2.1, 2.2, 2.3 
Fastopen 3.47 
Fc 3.48 
Fdisk 3.51 
Find 2.5, 3.52 
For 4.14 
Format 1.3, 2.2, 3.54 
Goto 4.16 
Graftabl 3.58 
Graphics 3.60 
If 4.17 
internal 2.1 
Join 3.62 
Keyb 3.64 
Label 3.66 
Mkdir 1.11, 3.68 
Mode 3.69 
More 2.5, 3.74 
Nisfunc 3.76 
Path 2.3, 3.77 
Pause 4.19 
Print 3.78 
Prompt 3.81 
Recover 3.83 
Rem 4.20 
Ren 3.84 
Replace 3.85 
Restore 3.88 
Rmdir 1.12, 3.90 
Select 3.91 
Set 3.93 


MS-DOS command (continued) 
Set, used with link 7.9 
Share 3.95 
Shift 4.8, 4.21 
Sort 2.5, 3.96 
Subst 3.98 
syntax 3.4 
Sys 3.99 
Time 3.100 
Tree 3.102 
Type 2.2, 3.103 
Ver 3.104 
Verify 3.105 
Vol 3.106 
Xcopy 3.107 

MS-DOS commands, listing of 3.6 

MS-DOS prompt 
allowed characters 3.81 
command 3,81 
default drive letter A.1 
default setting 3.81 
special prompts 3.81 

MS-DOS version number, 
displaying 3.104 

Multilevel directory 1.3, 1.7 
Mkdir command 3.68 
removing a directory 3.90 
using wildcards with 1.9 


Name command, debug 
abbreviation 8.22 
comments 8.22 
purpose 8.22 
syntax 8.22 

National language support 
code pages E.1 
MS-DOS E.1 

Near segment-relative reference, 
link 7.27 

Near self-relative reference, link 
7.27 

Nesting batch file 4.12 

Network 3.2 

Network symbol 3.2 
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Nlsfunc command 
code pages E.3 
purpose 3.76 
syntax 3.76 
NOT parameter, if command 4.17 


NUL data path 3.9, 3.77 
Numenc parameter C.4 


Object file, link 7.2 
Object linker. See Link 
Omitting options, Edlin 6.22 
One-drive system A.1 
Opcodes, debug 8.8 
Operating system 
exiting to from Edlin 6.26 
definition x 
Operation modes 3.69 
Options, command 3.5 
Order of segments, link 7.24 
Organizing files 1.4, 1.7 
Output 2.4 
appending 2.4 
redirecting 2.4 
sending to lineprinter 5.7 
stopping 5.7 
Output command, debug 
abbreviation 8.24 
comments 8.24 
purpose 8.24 
syntax 8.24 
Overlay, link 7.5, 7.21 


Packing executable files 7.14 
Page command, Edlin 

purpose 6.25 

syntax 6.25 
Paging through files, Edlin 6.25 
Parallel printer 

code page switching 3.71 
Parameter 

changing position of 4.21 

condition 4.17 
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Parameter (continued) 
definition 4.7 
line C.4 
named 4.8 
numeric C.4 
replaceable 4.7, 4.10 
selecting C.4 
shifting 4.21 
Parent directory 
chdir command 3.21 
parent directory 1.8 
shorthand notation 1.8 
Parity 3.70 
Path 
definition 3.4 
NUL 3.77 
specifying a working path 2.3 
syntax 3.4 
using with internal commands 2.2 
Path command 2.3 
purpose 3.77 
syntax 3.77 
Pathname 
as a command option 3.4 
definition 1.7 
maximum length 1.8 
searching 1.8 
syntax 1.7, 3.4 
used with Chdir command 1.11 
using with intemal commands 2.2 
Pause command, batch 
purpose 4.19 
syntax 4,19 
Percent sign, used in a batch file 4.8 
Permission 
read-only 3.13 
write 3.13 
Pipe 2.4, 3.96 
Pipe symbo! (; ) 2.5 
Pipe, sort command 3.97 
Pipeline, definition 2.6 
Piping and redirecting 
definition 2.4 


Piping and redirecting (continued) 
input 2.6 
output 2.6 
Piping commands 2.5 
Placeholders 4.7 
Port, asynchronous communications 
COMI 3.70 
COM2 3.70 
Preserving lowercase characters, 
link 7.16 
Print command 
purpose 3.78 
switch 
[bo 3.78 
ic 3.79 
ld 3.78 
/p 3.78 
/q 3.78 
A 3.79 
syntax 3.78 
Print queue 
cancel mode 3.79 
deleting files from 3.79 
print mode 3.79 
Printer 3.78 
Printer, serial 3.70 
Pnnter.sys file 
code pages E.4 
country-specific E.4 
PRN, default printer 3.78 
Processing, batch files 3.93, 4.1, 
4.14 
Processing, interactive 4.14 
Processor, command B.13 
Program 
autoexec.bat 2.4 
batch 3.111 
command.com 2.1 
diskcopy.exe 2.2 
format.exe 2.2 
Program, executable 7.4 
Prompt 
$3.81 
> 3.81 


Prompt (continued) 
<101 3.81 
ASCII code (escape) 3.81 
asterisk (*), Edlin 6.2 
date 3.81 
default drive 3.81 
default drive letter A.1 
RETURN-LINEFEED 3.81 
space 3.81 
time 3.81, 3.100 
version number 3.81 
working directory, default drive 
3.81 
pipe (|) 3.81 
Prompt command 
purpose 3.81 
syntax 3.81 
Prompt, MS-DOS 3.81 
Protecting files 1.2 
Public-symbol 7.10 
Public-symbol map 7.15 


Question mark (?), wildcard 
character 1.9 

Question mark option, Edlin 6.13, 
6.30 

Queue, print 3.79 

Quit command, debug 
abbreviation 8.25 
comments 8.25 
purpose 8.25 
syntax 8.25 

Quit command, Edlin 
purpose 6.26 
syntax 6.26 

Quitting Edlin 6.3, 6.26 

Quotation marks, use of 3.52 


Ramdrive.sys C.1 
Rapid Blink function, ANSI C.4 
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RCP-Restore Cursor Position, ANSI 
escape sequence C.3 
Read-only file, restoring 3.88 
Read-only permission 3.13 
Recover command 
purpose 3.83 
syntax 3.83 
Recovering a file 3.83 
Redirecting and piping 
input 2.6 
output 2.6 
Redirecting parallel printer output 
3.69 
Redirection and piping symbols 2.4, 
2.5, 4.3 
Redirection symbol 
greater-than sign (>) 2.4 
less-than sign (<) 2.5 
two greater-than signs (>>) 2.4 
Register command, debug 
abbreviation 8.26 
comments 8.26 
purpose 8.26 
syntax 8.26 
Relative address, fc 3.48 
Rem command, batch 
purpose 4.20 
syntax 4.20 
Remark, batch file 4.20 
Removing 
directory 1.2, 3.90 
file 1.13, 3.36 
virtual drive 3.98 
Removing groups from a program, 
link 7.20 
Ren command 
purpose 3.84 
syntax 3.84 
using wildcards with 3.84 
Renaming a directory 1.13 
Renaming a file 3.84 
Replace command 
purpose 3.85 
syntax 3.85 
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Replace command, Edlin 
purpose 6.27 
syntax 6.27 
Replace mode, Edlin 6.8 
Replaceable parameter 3.93, 4.7, 
4.8,4.10 
Replacing text, Edlin 6.27 
Responding to errors F.1 
Response file, link 7.7 
Restore command 
code pages E.4 
purpose 3.88 
switch 
/a 3.88 
/b 3.88 
/e 3.88 
/L 3.88 
/m 3.88 
/n 3.88 
/p 3.88 
/s 3.88 
syntax 3.88 
Restoring 
file 3.88 
subdirectory 3.88 
RETURN-LINEFEED prompt 3.81 
Reverse sorting (Z to A) 3.96 
Reverse Video function, ANSI C.4 
Revising text, Edlin 6.1 
RM-Reset Mode, ANSI escape 
sequence C.5 
Rmdir command 
hidden files 3.90 
purpose 3.90 
shorthand notation 1.13 
syntax 3.90 
Root directory 
autoexec.bat 3.113 
config.sys file B.1 
definition 1.3 
joining with 3.62 
making subdirectories 3.68 
shorthand notation 1.7 
subdirectones of 1.6 


Running a batch file 4.9 


Sample config.sys B.2 
Saving a file, Edlin 6.3 
SCP-Save Cursor Position, ANSI 
escape sequence C.3 
Screen 
changing C.2 
code page switching 3.71, E.6 
erasing C.4 
graphics C.4 
width, changing C.5 
Screen code pages, selecting E.8 
Search command, debug 
abbreviation 8.29 
comments 8.29 
purpose 8.29 
syntax 8.29 
Search command, Edlin 
purpose 6.30 
syntax 6.30 
Search path 3.77 
Search path, link 7.9 
Searching a directory 3.77 
Searching for a file 1.5 
Searching for text 2.5 
Searching for text, Edlin 6.30 
Sector 3.83 
Segment alignment, link 7.24 
Segment number, setting maximum 
7.22 
Segment order, MS-DOS 
convention 7.22 
Select command 
code pages E.3 
purpose 3.91 
syntax 3.91 
Selective parameter C.2 
Semicolon, used for options 3.5 
Separating files 1.3 


Separator 
equal sign 4.16 
semicolon 4.16 
Separators in comments 
comma 4.20 
space 4.20 
tab 4.20 
Sequences of commands 3.93 
Serial printer 3.70 
Set command 
purpose 3.95 
syntax 3.95 
Set command, used with link F.1 
Setting a working path 2.4 
SGR-Set Graphics Rendition, ANSI 
escape sequence C.4 
Share command 
purpose 3.95 
syntax 3.95 
Sharing violation F.51 
Shell 
definition B.13 
starting B.13 
Shell command, config.sys file 
definition B.2 
purpose B.13 
syntax B.13 
Shift command 4.8 
Shift command, batch 
purpose 4.21 
syntax 4.21 
Shifting parameters 4.21 
Short reference, link 7.27 
Shortcuts 
asterisk (*) 1.9 
Chdir command 1.12, 3.21 
directory 
"." 3.90 
".." 3.90 
parent directory 1.8 
question mark (?) 1.9 
Rmdir command 3.90 
wildcard characters 1.9 
working directory 1.8 
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Shorthand notation. See Shortcuts 
Sign 
greater-than (>) 2.4 
less-than (<) 2.4 
Single-drive system A.1 
Skipping over template characters 
5.6 
Sort command 2.5 
filter 3.97 
pipe 3.97 
purpose 3.96 
switch 
/+n 3.96 
/r 3.96 
syntax 3.96 
Sorter.bat file 4.7, 4.9 
Sorting 
alphabetically (A to Z) 4.9 
directory 2.6 
file 2.5, 3.96 
reverse order (Z to A) 3.96 
Source drive 3.4 
Space prompt 3.81 
Spaces and tabs, used for options 
3.5 
Special editing key 
DEL 5.3 
description 6.4 
Esc 5.3 
F1 5.2 
F2 5.2 
F3 5.2 
F4 5.3 
F5 5.3 
F6 5.3 
Ins 5.3 
listing of 6.10 
using with Edlin 6.1 
Specifying a working path 2.3 
Stack size, controlling with link 
TAT 
Starting Edlin 6.2 
Stopbit 3.70 
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Stopping a command 3.19, 5.7 
Stopping Edlin 6.3 
String 
definition 3.5 
environment 3.93, 4.3 
finding 3.52 
invalid separators 
comma 4.17 
equal sign 4.17 
semicolon 4.17 
space 4.17 
replacing, Edlin 6.27 
searching, Edlin 6.30 
String, debug 8.6 
Structure 
directory 1.5 
file 1.5 
hierarchical 1.5 
multilevel 1.5 
Subdirectory 1.4, 1.6, 1.12 
Subdirectory, restoring 3.88 
Subfunction C.2 
Subscript function, ANSI C.4 
Subst command 
purpose 3.98 
syntax 3.98 
Superscript function, ANSI C.4 
Switch 
definition 3.4 
syntax 3.4 
Symbol 
greater-than sign (>) 2.4 
less-than sign (<) 2.4 
redirection 4.3 
Symbol-map file 
format 7.10 
Synonym, Del/Erase 3.36 
Syntax 
command 3.4 
path 3.4 
pathname 1.7, 3.4 
switch 3.4 
command. See Command syntax 


Sys command 
purpose 3.99 
syntax 3.99 
System files, transferring 3.99 
System prompt A.1 
System, file 1.4 


Target drive 3.4 
Template 
advantages of 5.1 
automatic overwriting 5.5 
dealing with misspellling 5.5 
deleting contents of 6.8, 6.9 
relation to command line 5.2 
using the BKSP key with 6.9 
using the DEL key with 6.6 
using the EXC key with 6.7 
using the Fi key with 6.5 
using the F2 key with 6.5 
using the F4 key with 6.7 
using the F5 key key with 6.8 
using the INS key with 6.8 
Template character 
copying 5.6 
deleting 5.6 
inserting 5.6 
skipping over 5.6 
Temporary file 
deleting 4.10 
purpose 4.10 
used in batch proocessing 4.7 
used with the more command 
3.74 
Temporary file, link 7.11 
Terminating a batch program 4.19 
Text editor, Edlin 1.11 
Text file, creating with Edlin 6.1 
Text option, Edlin 6.13 
Text, moving, Edlin 6.23 
Text, searching for 2.5 
Time command 
code pages E.4 


Time command (continued) 
purpose 3.100 
syntax 3.100 
Time format, country-specific E.5 
Time prompt 3.81, 3.100 
Trace command, debug 
abbreviation 8.30 
comments 8.30 
purpose 8.30 
syntax 8.30 
Transfer command, Edlin 
purpose 6.32 
syntax 6.32 
Transferring system files 3.99 
Transferring text, Edlin 6.32 
Transmission rate 3.70 
Tree command 
purpose 3.102 
syntax 3.102 
Two-letter code, keyb command 
3.64 
Type command 2.2 
purpose 3.103 
syntax 3.103 
Typical config.sys file B.2 


Unassemble command, debug 
abbreviation 8.31 
comments 8.31 
purpose 8.31 
syntax 8.31 

Underline, cursor 5.4 

Updating the system 3.99 

Uppercase letter, use of 6.22 

Uppercase letters 7.16, 8.3 

User directory 1.6 

Using code pages E.1 


Variable, replaceable 3.93, 4.8 
Ver command 

purpose 3.104 

syntax 3.104 
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Verify command 
purpose 3.105 
syntax 3.105 
Version number prompt 3.81 
Version number, displaying 3.104 
Vertical bar. See Pipe symbol (; ) 
Virtual drive 
creating 3.98 
definition 3.98 
removing 3.98 
Vm.tmp file, link 7.11 
Vol command 
purpose 3.106 
syntax 3.106 
Volume label 
allowed characters 3.66 
creating 3.66 
deleting 3.66 
displaying 3.106 
length 3.67 


Wildcard character 
astensk (*) 1.9 
destructive uses of 1.10 
question mark (?) 1.9 
shortcuts 1.9 
special uses 1.10 
using the asterisk (*) 1.9 
using the question mark (?) 1.9 
Working directory 1.6 
definitions 1.5 
displaying 1.11, 3.21 
external command directory 2.3 
Mkdir command 3.68 
program directory 2.3 
prompt, default drive 3.81 
searching for data files in 3.9 
shorthand notations 1.8 
using filenames 1.8 
using pathnames 1.8 
Working path 2.3 
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Write command, debug Wnite-protected disk 3.74 
abbreviation 8.33 Write-protection 1.2 
comments 8.33 Writing to 
purpose 8.33 a disk 3.105 
syntax 8.33 a disk, Edlin 6.33 

Write command, Edlin 
purpose 6.33 Xcopy command 
syntax 6.33 purpose 3.107 

Write-protect notch 1.2, F.59 syntax 3.107 


Write-protect tab F.59 
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Microsoft® Gw-BAsic® is a simple, easy-to-learn, easy-to-use computer 
programming language with English-like statements and mathematical 
notations. With cw-Basic you will be able to write both simple and complex 
programs to run on your computer. You will also be able to modify existing 
software that is written in GW-BASIC. 


This guide is designed to help you use the cw-nasic Interpreter with the Ms-Dos® 
operating system. Section 1.5 lists resources that will teach you how to 
program. 


1.1 System Requirements 


This version of Gw-BAsic requires Ms-Dos version 3.2 or later. 


1.2 Preliminaries 


Your cw-sasic files will be on the Ms-pos diskette located at the back of the MS- 
DOS User's Reference. Be sure to make a working copy of the diskette before 
you proceed. 


Note This manual is written for the user familiar with the ms-Dos operating 
system. For more information on Ms-bos, refer to the Microsoft MS-DOS 3.2 
User's Guide and User's Reference. 
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1.3 Notational Conventions 


Throughout this manual, the following conventions are used to distinguish 
elements of text: 


bold Used for commands, options, switches, and literal por- 
tions of syntax that must appear exactly as shown. 


italic Used for filenames, variables, and placeholders that 
represent the type of text to be entered by the user. 


monospace Used for sample command lines, program code and 
examples, and sample sessions. 

SMALL CAPS Used for keys, key sequences, and acronyms. 

Brackets surround optional command-line elements. 


1.4 Organization of This Manual 


The GW-BASIC User's Guide is divided into six chapters, nine appendixes, and 
a glossary: 

Chapter 1, "Welcome to GW-BASIC," describes this manual. 

Chapter 2, "Getting Started With GW-BASIC,” is an elementary guideline on 
how to begin programming. 

Chapter 3, "Reviewing and Practicing GW-BASIC," lets you use the principles 
of GW-BASIC explained in Chapter 2. 

Chapter 4, "The GW-BASIC Screen Editor,” discusses editing commands that 
can be used when inputting or modifying a Gw-Basic program. It also explains 
the unique properties of the ten redefinable function keys and of other keys and 
keystroke combinations. 

Chapter 5, "Creating and Using Files,” tells you how to create files and to use 
the diskette input/output (I/O) procedures. 


Welcome to GW-BASIC 1.5 


Chapter 6, "Constants, Variables, Expressions, and Operators," defines the 
elements of cw-Basic and describes how you will use them. 

Appendix A, "Error Codes and Messages," is a summary of all the error codes 
and error messages that you might encounter while using Gw-BASIC. 

Appendix B, "Mathematical Functions," describes how to calculate certain 
mathematical functions not intrinsic to Gw-BASIC. 

Appendix C, "ascu Character Codes,” lists the ascu character codes recognized 
by Gw-BASIc. 

Appendix D, "Assembly Language (Machine Code) Subroutines," shows how 
to include assembly language subroutines with Gw-BAsic. 

Appendix E, "Converting BASIC Programs to GW-BASIC," provides pointers 
on converting programs written in BASIC tO GW-BASIC. 

Appendix F, “Communications,” describes the Gw-Basic statements required to 
support RS-232 asynchronous communications with other computers and 
peripheral devices. 

Appendix G, "Hexadecimal Equivalents," lists decimal and binary equivalents 
to hexadecimal values. 

Appendix H, "Key Scan Codes," lists and illustrates the key scan code values 
used in GW-BASIC. 

Appendix I, "Characters Recognized by GW-BASIC," describes the Gw-BAsIc 
character set. 


The Glossary defines words and phrases commonly used in Gw-Basic and data 
processing. 
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1.5 Bibliography 


This manual is a guide to the use of the cw-sasic Interpreter: it makes no 
attempt to teach the Basic programming language. The following texts may be 
useful for those who wish to learn Basic programming: 


Albrecht, Robert L., LeRoy Finkel, and Jerry Brown. BASIC. 2d ed. New York: 
Wiley Interscience, 1978. 


Coan, James. Basic BASIC. Rochelle Park, N.J.: Hayden Book Company, 1978. 


Dwyer, Thomas A. and Margot Critchfield. BASIC and the Personal Computer. 
Reading, Mass.: Addison-Wesley Publishing Co., 1978. 


Ettlin, Walter A. and Gregory Solberg. The MBASIC Handbook. Berkeley, 
Calif.: Osborne/McGraw Hill, 1983. 


Knecht, Ken. Microsoft BASIC. Portland, Oreg.: Dilithium Press, 1982. 
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This chapter describes how to load Gw-sasic into your system. It also explains 
the two different types of operation modes, line formats, and the various 
elements of GW-BASIC. 


2.1 Loading GW-BASIC 


To use the cw-sasic language, you must load it into the memory of your 
computer from your working copy of the ms-pos diskette. Use the following 
procedure: 

1. Tum on your computer. 


2. Insert your working copy of the Ms-pos diskette into Drive A of your 
computer, and press RETURN. 


3. Type the following command after the A> prompt, and press RETURN: 
gwbasic 


Once you enter Gw-sasic, the Gw-BAsic prompt, Ok, will replace the Ms-Dos 
prompt, A>. 


On the screen, the line XXXXX Bytes Free indicates how many bytes are 
available for use in memory while using Gw-BAsIc. 


The function key (F1 - F10) assignments appear on the bottom line of the 
screen. These function keys can be used to eliminate key strokes and save you 
time. Chapter 4, "The GW-BASIC Screen Editor," contains detailed 
information on function keys. 


2.2 Modes of Operation 


Once cw-asic is initialized (loaded), it displays the Ok prompt. Ok means cw- 
BASIC is at command level; that is, it is ready to accept commands. At this point, 
GW-BASIc may be used in either of two modes: direct mode or indirect mode. 
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2.2.1 Direct Mode 


In the direct mode, Gw-Basic statements and commands are executed as they are 
entered. Results of arithmetic and logical operations can be displayed 
immediately and/or stored for later use, but the instructions themselves are lost 
after execution. This mode is useful for debugging and for using Gw-BASIC as a 
calculator for quick computations that do not require a complete program. 


2.2.2 Indirect Mode 


The indirect mode is used to enter programs. Program lines are always 
preceded by line numbers, and are stored in memory. The program stored in 
memory is executed by entering the RUN command. 


2.3 The GW-BASIC Command Line Format 


The cw-Basic command line lets you change the environment or the conditions 
that apply while using Gw-BAsic. 


Note When you specify modifications to the operating environment of cw- 
BASIC, be sure to maintain the parameter sequence shown in the syntax 
statement. To skip a parameter, insert a comma. This will let the computer 
know that you have no changes to that particular parameter. 


GW-BASIC uses a command line of the following form: 
gwhbasic[filename][<stdin]}[[>]>stdout][/f:n][/i}[/s:n)[/e:n][/m:[”][,1)][/d] 
filename is the name of a cw-Basic program file. If this parameter is present, Gw- 
BASIC proceeds as if a RUN command had been given. If no extension is 
provided for the filename, a default file extension of .BAS is assumed. The 
-BAS extension indicates that the file is a cw-sasic file. The maximum number 
of characters a filename may contain is eight with a decimal and three 
extension characters. 
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<stdin redirects Gw-Basic’s standard input to be read from the specified file. 
When used, it must appear before any switches. 


This might be used when you have multiple files that might be used by your 
program and you wish to specify a particular input file. 

>stdout redirects Gw-Basic’s standard output to the specified file or device. 
When used, it must appear before any switches. Using >> before stdout causes 
output to be appended. 


Gw-Basic can be redirected to read from standard input (keyboard) and write to 
standard output (screen) by providing the input and output filenames on the 
command line as follows: 

gwbasic program name <input file[>]>output file 

An explanation of file redirection follows this discussion of the Gw-BAsic 
command line. 

Switches appear frequently in command lines; they designate a specified course 
of action for the command, as opposed to using the default for that setting. A 
switch parameter is preceded by a slash (/). 


/f:n sets the maximum number of files that may be opened simultaneously 
during the execution of a Gw-Basic program. Each file requires 194 bytes for the 
File Control Block (FCB) plus 128 bytes for the data buffer. The data buffer 
size may be altered with the /s: switch. If the /f: switch is omitted, the 
maximum number of open files defaults to 3. This switch is ignored unless the 
fi switch is also specified on the command line. 


/i makes Gw-sasic statically allocate space required for file operations, based on 
the /s and /f switches. 


/s:n sets the maximum record length allowed for use with files. The record 
length option in the OPEN statement cannot exceed this value. If the /s: switch 
is omitted, the record length defaults to 128 bytes. The maximum record size is 
32767. 


[c:n controls RS-232 communications. If RS-232 cards are present, /c:0 
disables RS-232 support, and any subsequent I/O attempts for each RS-232 
card present. If the /c: switch is omitted, 256 bytes are allocated for the receive 
buffer and 128 bytes for the transmit buffer for each card present. 


2.6 GW-BASIC User's Guide 


The /c: switch has no affect when RS-232 cards are not present. The /c:n switch 
allocates n bytes for the receive buffer and 128 bytes for the transmit buffer for 
each RS-232 card present. 


/m:n[,n] sets the highest memory location (first n) and maximum block size 
(second n) used by Gw-BASIC. GW-BASIC attempts to allocate 64K bytes of 
memory for the data and stack segments. If machine language subroutines are 
to be used with Gw-sasic programs, use the /m: switch to set the highest 
location that Gw-Basic can use. The maximum block size is in multiples of 16. It 
is used to reserve space for user programs (assembly language subroutines) 
beyond Gw-sasic’s workspace. 


The default for maximum block size is the highest memory location. The 
default for the highest memory location is 64K bytes unless maximum block 
size is specified, in which case the default is the maximum block size (in 
multiples of 16). 


/d allows certain functions to return double-precision results. When the /d 
switch is specified, approximately 3000 bytes of additional code space are 
used. The functions affected are ATN, COS, EXP, LOG, SIN, SQR, and TAN. 


Note All switch numbers may be specified as decimal, octal (preceded by 
&QO), or hexadecimal (preceded by &H). 


Sample Gw-Basic command lines are as follows: 


The following uses 64K bytes of memory and three files; loads and executes 
the program file payroll.bas: 


A>gwbasic PAYROLL 


The following uses 64K bytes of memory and six files; loads and executes the 
program file invent.bas: 


A>gwbasic INVENT /F:6 
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The following disables RS-232 support and uses only the first 32K bytes of 
memory. 32K bytes above that are reserved for user programs: 


A>gwbasic /C:0 /M:32768, 4096 


The following uses four files and allows a maximum record length of 512 
bytes: 


A>gwbasic /F:4 /S:512 


The following uses 64K bytes of memory and three files. Allocates 512 bytes to 
RS-232 receive buffers and 128 bytes to transmit buffers, and loads and 
executes the program file tty.bas: 


A>gwbasic TTY /C:512 


For more information about RS-232 Communications, see Appendix F. 


Redirection of Standard Input and Output 


When redirected, all INPUT, LINE INPUT, INPUTS, and INKEY$ statements 
are read from the specified input file instead of the keyboard. 


All PRINT statements write to the specified output file instead of the screen. 
Error messages go to standard output and to the screen. 

File input from KYBD: is still read from the keyboard. 

File output to SCRN: still outputs to the screen. 

GW-BASIC continues to trap keys when the ON KEY n statement is used. 


Typing CTRL-BREAK when output is redirected causes Gw-BASIc to close any open 
files, issue the message "Break in line nnnn" to standard output, exit Gw-BASIC, 
and return to MS-DOS. 


When input is redirected, Gw-Basic continues to read from this source until a 
CTRL-Z is detected. This condition can be tested with the end-of-file (EOF) 
function. If the file is not terminated by a cTRL-z, or if a Gw-pasic file input 
statement tries to read past the end of file, then any open files are closed, and 
GW-BASIC returns to MS-DOS. 
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For further information about these statements and other statements, functions, 
commands, and variables mentioned in this text, refer to the GW-BASIC User's 
Reference. 


Some examples of redirection follow. 
GWBASIC MYPROG >DATA. OUT 


Data read by the INPUT and LINE INPUT statements continues to come from 
the keyboard. Data output by the PRINT statement goes into the data.out file. 


gwbasic MYPROG <DATA.IN 


Data read by the INPUT and LINE INPUT statements comes from data.in. 
Data output by PRINT continues to go to the screen. 


gwbasic MYPROG <MYINPUT.DAT >MYOUTPUT.DAT 


Data read by the INPUT and LINE INPUT statements now come from the file 
myinput.dat, and data output by the PRINT statements goes into myoutput.dat. 


gwbasic MYPROG <\SALES\JOHN\TRANS.DAT 
>>\SALES\SALES. DAT 


Data read by the INPUT and LINE INPUT statements now comes from the file 
\sales\john\trans.dat. Data output by the PRINT statement is appended to the 
file \sales\sales.dat. 


2.4 GW-BASIC Statements, Functions, 
Commands, and Variables 


A Gw-BASIC program is made up of several elements: keywords, commands, 
statements, functions, and variables. 


2.4.1 Keywords 


GW-BASIC keywords, such as print, goto, and return have special significance 
for the cw-sasic Interpreter. Gw-Basic interprets keywords as part of statements 
or commands. 
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Keywords are also called reserved words. They cannot be used as variable 
names, or the system will interpret them as commands. However, keywords 
may be embedded within vanable names. 


Keywords are stored in the system as tokens (1- or 2-byte characters) for the 
most efficient use of memory space. 


2.4.2 Commands 


Commands and statements are both executable instructions. The difference 
between commands and statements is that commands are generally executed in 
the direct mode, or command level of the interpreter. They usually perform 
some type of program maintenance such as editing, loading, or saving 
programs. When cw-sasic is invoked and the Gw-sasic prompt, Ok, appears, the 
system assumes command level. 


2.4.3 Statements 


A statement, such as ON ERROR...GOTO, is a group of cw-Basic keywords 
generally used in Gw-BAsic program lines as part of a program. When the 
program is run, statements are executed when, and as, they appear. 


2.4.4 Functions 


The Gw-nasic Interpreter performs both numeric and string functions. 


2.4.4.1 Numeric Functions 


The cw.-sasic Interpreter can perform certain mathematical (arithmetical or 
algebraic) calculations. For example, it calculates the sine (sin), cosine (cos), or 
tangent (tan) of angle x. 


Unless otherwise indicated, only integer and single-precision results are 
returned by numeric functions. 
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2.4.4.2 String Functions 


String functions operate on strings. For example, TIMES and DATES return the 
time and date known by the system. If the current time and date are entered 
during system start up, the correct time and date are given (the internal clock in 
the computer keeps track). 


2.4.4.3 User-Defined Functions 


Functions can be user-defined by means of the DEF FN statement. These 
functions can be either string or numeric. 


2.4.5 Variables 


Certain groups of alphanumeric characters are assigned values and are called 
variables. When variables are built into the Gw-Basic program they provide 
information as they are executed. 


For example, ERR defines the latest error which occurred in the program; ERL 
gives the location of that error. Variables can also be defined and/or redefined 
by the user or by program content. 


All cw-Basic commands, statements, functions, and variables are individually 
described in the GW-BASIC User's Reference. 


2.5 Line Format 


Each of the elements of cw-Basic can make up sections of a program that are 
called statements. These statements are very similar to sentences in English. 
Statements are then put together in a logical manner to create programs. The 
GW-BASIC User's Reference describes all of the statements available for use in 
GW-BASIC. 


In a Gw-BAsic program, lines have the following format: 
mnnnn statement|statements] 
nnnnn is a line number. 


Statement is a GW-BASIC statement. 
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A Gw-BASIC program line always begins with a line number and must contain at 
least one character, but no more than 255 characters. Line numbers indicate the 
order in which the program lines are stored in memory, and are also used as 
references when branching and editing. The program line ends when you press 
the RETURN key. 


Depending on the logic of your program, there may be more than one statement 
on a line. If so, each must be separated by a colon (:). Each of the lines in a 
program should be preceded by a line number. This number may be any whole 
integer from 0 to 65529. It is customary to use line numbers such as 10, 20, 30, 
and 40, in order to leave room for any additional lines that you may wish to 
include later. Since the computer will run the statements in numerical order, 
additional lines needn’t appear in consecutive order on the screen: for example, 
if you entered line 35 after line 60, the computer would still run line 35 after 
line 30 and before line 40. This technique may save your reentering an entire 
program in order to include one line that you have forgotten. 


The width of your screen is 80 characters. If your statement exceeds this width, 
the cursor will wrap to the next screen line automatically. Only when you press 
the RETURN key will the computer acknowledge the end of the line. Resist the 
temptation to press RETURN as you approach the edge of the screen (or beyond). 
The computer will automatically wrap the line for you. You can also press 
CTRL-RETURN , Which causes the cursor to move to the beginning of the next 
screen line without actually entering the line. When you press RETURN , the 
entire logical line is passed to Gw-sasic for storage in the program. 


In cw-sasic, any line of text that begins with a numeric character is considered a 
program line and is processed in one of three ways after the RETURN key is 
pressed: 


e A new line is added to the program. This occurs if the line number is legal 
(within the range of 0 through 65529), and if at least one alpha or special 
character follows the line number in the line. 


e An existing line is modified. This occurs if the line number matches the 
line number of an existing line in the program. The existing line is 
replaced with the text of the newly-entered line. This process is called 
editing. 
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Note Reuse of an existing line number causes all of the information contained 
in the original line to be lost. Be careful when entering numbers in the indirect 
mode. You may erase some program lines by accident. 


èe — An existing line is deleted. This occurs if the line number matches the line 
number of an existing line, and the entered line contains only a line 
number. If an attempt is made to delete a nonexistent line, an "Undefined 
line number” error message is displayed. 


2.6 Returning to MS-DOS 


Before you return to MS-Dos, you must save the work you have entered under 
GW-BASIC, or the work will be lost. 


To return to Ms-bos, type the following after the Ok prompt, and press RETURN: 


system 


The system returns to MS-DOS, and the A> prompt appears on your screen. 


3 Reviewing and Practicing 
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3.1 Example for the Direct Mode 3.3 
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3.4 Editing Lines 3.6 
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The practice sessions in this chapter will help you review what you have 
learned. If you have not done so, this is a good time to turn on your computer 
and load the cw-sasic Interpreter. 


3.1 Example for the Direct Mode 


You can use your computer in the direct mode to perform fundamental 
arithmetic operations. Gw-Basic recognizes the following symbols as arithmetic 
operators: 


Operation GW-BASIC Operator 
Addition + 
Subtraction - 
Multiplication * 
Division / 


To enter a problem, respond to the Ok prompt with a question mark (?), 
followed by the statement of the problem you want to solve, and press the 
RETURN key. In Gw-asic, the question mark can be used interchangeably with 
the keyword PRINT. The answer is then displayed. 


Type the following and press the RETURN key: 
?2+2 
GW-BASIC Will display the answer on your screen: 


?2+2 
4 
Ok 


To practice other arithmetic operations, replace the + sign with the desired 
operator. 


The cw-sasic language is not restricted to arithmetic functions. You can also 
enter complex algebraic and trigonometric functions. The formats for these 
functions are provided in Chapter 6, "Constants, Variables, Expressions and 
Operators.” 
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3.2 Examples for the Indirect Mode 


The cw-sasic language can be used for functions other than simple algebraic 
calculations. You can create a program that performs a series of operations and 
then displays the answer. To begin programming, you create lines of 
instructions called statements. Remember that there can be more than one 
statement on a line, and that each line is preceded by a number. 


For example, to create the command PRINT 2+3 as a statement, type the 
following: 


10 print 2+3 


When you press the RETURN key, the cursor shifts to the next line, but nothing 
else happens. To make the computer perform the calculation, type the 
following and press the RETURN key: 


run 
Your screen should look like this: 


Ok 
10 print 2+3 
run 
5 
Ok 


You have just written a program in Gw-BASIC. 


The computer reserves its calculation until specifically commanded to continue 
(with the RUN command). This allows you to enter more lines of instruction. 
When you type the RUN command, the computer does the addition and 
displays the answer. 


The following program has two lines of instructions. Type it in: 


10 x=3 
20 print 2+x 


Now use the RUN command to have the computer calculate the answer. 
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Your screen should look like this: 


Ok 
10 x=3 
20 print 2+x 
run 
5 
Ok 


The two features that distinguish a program from a calculation are 


1. the numbered lines 
2. the use of the RUN command 


These features let the computer know that all the statements have been typed 
and the computation can be carried out from beginning to end. It is the 
numbering of the lines that first signals the computer that this is a program, not 
a calculation, and that it must not do the actual computation until the RUN 
command is entered. 


In other words, calculations are done under the direct mode. Programs are 
written under the indirect mode. 


To display the entire program again, type the LIST command and press the 
RETURN key: 


list 
Your screen should look like this: 


Ok 
10 x=3 
20 print 2+x 
run 
Ok 
5 
Ok 
list 
10 X=3 
20 PRINT 2+X 
Ok 


Yov’ll notice a slight change in the program. The lowercase letters you entered 
have been converted into uppercase letters. The LIST command makes this 
change automatically. 
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3.3 Function Keys 


Function keys are keys that have been assigned to frequently-used commands. 
The ten function keys are located on the left side of your keyboard. A guide to 
these keys and their assigned commands appears on the bottom of the Gw-sasic 
screen. To save time and keystrokes, you can press a function key instead of 
typing a command name. 


For example, to list your program again, you needn’t type the LIST command; 
you can use the function key assign to it, instead: 


1. Press the Fi key. 
2. Press RETURN. 


Your program should appear on the screen. 


To run the program, simply press the r2 key, which is assigned to the RUN 
command, 


As you learn more commands, you'll learn how to use keys F3 through Fio. 
Chapter 4, "The GW-BASIC Screen Editor,” contains more information about 
keys used in GW-BASIC. 


3.4 Editing Lines 


There are two basic ways to change lines. You can 


e Delete and replace them 
e Alter them with the EDIT command 


To delete a line, simply type the line number and press the RETURN key. For 
example, if you type /2 and press the RETURN key, line number 12 is deleted 
from your program. 


To use the EDIT command, type the command EDIT, followed by the number 
of the line you want to change. For example, type the following, and press the 
RETURN key: 


edit 10 
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You can then use the following keys to perform editing: 


Key Function 

CURSOR UP Moves the cursor within the statement 

CURSOR DOWN 

CURSOR LEFT 

CURSOR RIGHT 

BACKSPACE Deletes the character to the left of the cursor 
DELETE (DEL) Deletes the current character 

INSERT (INS) Lets you insert characters to the left of the cursor 


For example, to modify statement (line) 10 to read x=4, use the cursor-right 
control key to move the cursor under the 3, and then type a 4. The number 4 
replaces the number 3 in the statement. 


Now press the RETURN key, and then the F2 key. 
Your screen displays the following: 

Ok 

10 X=4 

RUN 


6 
Ok 


3.5 Saving Your Program File 


Creating a program is like creating a data file. The program is a file that 
contains specific instructions, or statements, for the computer. In order to use 
the program again, you must save it, just as you would a data file. 


To save a file in Gw-Basic, use the following procedure: 
1. Press the f4 key. 
The command word "SAVE" appears on your screen. 


2. Type aname for the program, and press the RETURN key. The file is saved 
under the name you specified. 
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To recall a saved file, use the following procedure: 
1. Press the F3 key. 
The command word "LOAD" appears on your screen. 
2. Type the name of the file. 
3. Press RETURN. 


The file is loaded into memory, and ready for you to list, edit, or run. 
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You can edit Gw-Basic program lines as you enter them, or after they have been 
saved in a program file. 


4.1 Editing Lines in New Files 


If an incorrect character is entered as a line is being typed, it can be deleted 
with the BACKSPACE or DEL keys, or with crru-n. After the character is deleted, 
you can continue to type on the line. 


The Esc key lets you delete a line from the screen that is in the process of being 
typed. In other words, if you have not pressed the RETURN key, and you wish to 
delete the current line of entry, press the Esc key. 


To delete the entire program currently residing in memory, enter the NEW 
command. NEW is usually used to clear memory prior to entering a new 
program. 


4.2 Editing Lines in Saved Files 


After you have entered your Gw-Basic program and saved it, you may discover 
that you need to make some changes. To make these modifications, use the 
LIST statement to display the program lines that are affected: 


1. Reload the program. 
2. Type the LIST command, or press the Fi key. 
3. Type the line number, or range of numbers, to be edited. 


The lines will appear on your screen. 


4.2.1 Editing the Information in a Program Line 


You can make changes to the information in a line by positioning the cursor 
where the change is to be made, and by doing one of the following: 


e Typing over the characters that are already there. 
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Deleting characters to the left of the cursor, using the BAckspAce key. 


Deleting characters at the cursor position using the DEL key on the number 
pad. 

e Inserting characters at the cursor position by pressing the ms key on the 
number pad. This moves the characters following the cursor to the right 
making room for the new information. 


e Adding to or truncating characters at the end of the program line. 


If you have changed more than one line, be sure to press RETURN on each 
modified line. The modified lines will be stored in the proper numerical 
sequence, even if the lines are not updated in numerical order. 


Note A program line will not actually have changes recorded within the cw- 
BASIC program until the RETURN key is pressed with the cursor positioned 
somewhere on the edited line. 


You do not have to move the cursor to the end of the line before pressing the 
RETURN key. The cw-sasic Interpreter remembers where each line ends, and 
transfers the whole line, even if RETURN is pressed while the cursor is located in 
the middle or at the beginning of the line. 

To truncate, or cut off, a line at the current cursor position, type CTRL-END or 
CTRL-E, followed by pressing the RETURN key. 

If you have originally saved your program to a program file, make sure that you 
save the edited version of your program. If you do not do this, your 
modifications will not be recorded. 


4.3 Special Keys 


The cw-sasic Interpreter recognizes nine of the numeric keys on the right side 
of your keyboard. It also recognizes the Backspace key, Esc key, and the CTRL 
key. The following keys and key sequences have special functions in Gw-BASIC: 


Key 
BACKSPACE Of CTRL-H 


CTRL-BREAK OT CTRL-C 


CTRL-CURSOR-LEFT 
OF CTRL-B 


CTRL-CURSOR-RIGHT 
OT CTRL-F 


CURSOR-DOWN 
or CTRL- — 


CURSOR-LEFT OT 
CTRL-] 


CURSOR-RIGHT OT 
CTRL-\ 


CURSOR-UP OF CTRL-6 


CTRL-BACKSPACE OT 
DEL 
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Function 


Deletes the last character typed, or deletes the 
character to the left of the cursor. All characters 
to the right of the cursor are moved left one 
position. Subsequent characters and lines within 
the current logical line are moved up as with the 
DEL key. 

Returns to the direct mode, without saving 
changes made to the current line. It will also exit 
auto line-numbering mode. 

Moves the cursor to the beginning of the 
previous word. The previous word is defined as 
the next character to the left of the cursor in the 
set A to Z or in the set 0 to 9. 

Moves the cursor to the beginning of the 

next word. The next word is defined as the next 
character to the right of the cursor in the set A to 
Z or in the set 0 to 9. In other words, the cursor 
moves to the next number or letter after a blank 
or other special character. 


Moves the cursor down one line on the screen. 


Moves the cursor one position left. When 

the cursor is advanced beyond the left edge of the 
screen, it will wrap to the right side of the screen 
on the preceding line. 

Moves the cursor one position right. When 

the cursor is advanced beyond the right edge of 
the screen, it will wrap to the left side of the 
screen on the following line. 

Moves the cursor up one line on the screen. 
Deletes the character positioned over the 

cursor. All characters to the right of the one 
deleted are then moved one position left to fill in 
where the deletion was made. 

If a logical line extends beyond one physical line, 
characters on subsequent lines are moved left one 
position to fill in the previous space, and the 
character in the first column of each subsequent 
line is moved up to the end of the preceding line. 
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CTRL-END OF CTRL-E 


CTRL-N OF END 


CTRL-RETURN OT 


CTRL-M OT RETURN 
CTRL-[ or ESC 

CTRL-G 

CTRL-K OF HOME 
CTRL-HOME OF CTRL-L 


CTRL-R OT INS 


DEL (delete) is the opposite of ms (insert). 
Deleting text reduces logical line length. 


Erases from the cursor position to the end of the 
logical line. All physical screen lines are erased 
until the terminating RETURN is found. 


Moves the cursor to the end of the logical line. 
Characters typed from this position are added to 
the line. 


Moves the cursor to the beginning of the 

next screen line. This lets you create logical 
program lines which are longer than the physical 
screen width. Logical lines may be up to 255 
characters long. This function may also be used 
as a line feed. 

Enters a line into the cw-sasic program. It also 
moves the cursor to the next logical line. 

Erases the entire logical line on which the cursor 
is located. 


Causes a beep to emit from your computer’s 
speaker. 

Moves the cursor to the upper left corner of the 
screen. The screen contents are unchanged. 


Clears the screen and positions the cursor in the 
upper left corner of the screen. 

Turns the Insert Mode on and off. Insert Mode is 
indicated by the cursor blotting the lower half of 
the character position. In Graphics Mode, the 
normal cursor covers the whole character 
position. When Insert Mode is active, only the 
lower half of the character position is blanked by 
the cursor. 


When Insert Mode is off, characters typed replace 
existing characters on the line. The SPACEBAR 
erases the character at the current cursor position 
and moves the cursor one character to the nght. 
The CursoR-RIGHT key moves the cursor one 
character to the right, but does not delete the 
character. 
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When Insert Mode is off, pressing the Tas key 
moves the cursor over characters until the next 
tab stop is reached. Tab stops occur every eight 
character positions. 

When Insert Mode is on, characters following the 
cursor are moved to the right as typed characters 
are inserted before them at the current cursor 
position. After each keystroke, the cursor moves 
one position to the right. Line wrapping is 
observed. That is, as characters move off the 
right side of the screen, they are inserted from 
the left on subsequent lines. Insertions increase 
logical line length. 

When Insert Mode is on, pressing the TAB key 
causes blanks to be inserted from current cursor 
position to the next tab stop. Line wrapping is 
observed as above. 


CTRL-NUM LOCK OT Places the computer in a pause state. 
CTRL-S To resume operation, press any other key. 
CTRL-PRTSC Causes characters printed on the screen to echo 


to the lineprinter (Ipt1:). In other words, you will 
be printing what you type on the screen. Pressing 
CTRL-PRTSC a second time turns off the echoing of 
characters to Iptl:. 


SHIFT - PRTSC Sends the current screen contents to the printer, 
effectively creating a snapshot of the screen. 
CTRL-I OF TAB Moves the cursor to the next tab stop. Tab stops 


occur every eight columns. 


4.4 Function Keys 


Certain keys or combinations of keys let you perform frequently-used 
commands or functions with a minimum number of keystrokes. These keys are 
called function keys. 
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The special function keys that appear on the left side of your keyboard can be 
temporarily redefined to meet the programming requirements and specific 
functions that your program may require. 


Function keys allow rapid entry of as many as 15 characters into a program 
with one keystroke. These keys are located on the left side of your keyboard 
and are labelled Fi through rio. w-Basic has already assigned special functions 
to each of these keys. You will notice that after you load cw-sasic these special 
key functions appear on the bottom line of your screen. These key assignments 
have been selected for you as some of the most frequently used commands. 


Initially, the function keys are assigned the following special functions: 


Table 4.1 

GW-BASIC Function Key Assignments 

Key Function Key Function 

F1 LIST F6 s 'LPT1:"<- 

F2 RUN<- F7 TRON<- 

F3 LOAD" F8 TROFF<- 

F4 SAVE" F9 KEY 

F5 CONT<- F10 SCREEN 0,0,0<- 


Note The <- following a function indicates that you needn’t press the RETURN 
key after the function key. The selected command will be immediately 
executed. 


If you choose, you may change the assignments of these keys. Any one or all of 
the 10 function keys may be redefined. For more information, see the KEY and 
ON KEY statements in the GW-BASIC User's Reference. 
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There are two types of files in MS-DOS systems: 


e Program files, which contain the program or instructions for the computer 


e Data files, which contain information used or created by program files 


5.1 Program File Commands 


The following are the commands and statements most frequently used with 
program files. The GW-BASIC User's Reference contains more information on 
each of them. 


SAVE filename[,a][,p] 
Writes to diskette the program currently residing in memory. 
LOAD filename[,r] 


Loads the program from a diskette into memory. LOAD deletes the current 
contents of memory and closes all files before loading the program. 


RUN filename{,r] 


Loads the program from a diskette into memory and runs it immediately. RUN 
deletes the current contents of memory and closes all files before loading the 
program. 


MERGE filename 


Loads the program from a diskette into memory, but does not delete the current 
program already in memory. 


KILL filename 
Deletes the file from a diskette. This command can also be used with data files. 
NAME old filename AS new filename 


Changes the name of a diskette file. Only the name of the file is changed. The 
file is not modified, and it remains in the same space and position on the disk. 
This command can also be used with data files. 
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5.2 Data Files 


GW-BASIC programs can work with two types of data files: 


e Sequential files 
e Random access files 


Sequential files are easier to create than random access files, but are limited in 
flexibility and speed when accessing data. Data written to a sequential file is a 
series of ascu characters. Data is stored, one item after another (sequentially), in 
the order sent. Data is read back in the same way. 


Creating and accessing random access files requires more program steps than 
sequential files, but random files require less room on the disk, because cw- 
BASIC stores them in a compressed format in the form of a string. 


The following sections discuss how to create and use these two types of data 
files. 


5.2.1 Creating a Sequential File 


The following statements and functions are used with sequential files: 


CLOSE LOF 

EOF OPEN 

INPUT# PRINT# 

LINE INPUT# PRINT# USING 
LOC UNLOCK 
LOCK WRITE# 


The following program steps are required to create a sequential file and access 
the data in the file: 


1. Open the file in output (O) mode. The current program will use this file 
first for output: 


OPEN "0",#1,"filename" 
2. Write data to the file using the PRINT# or WRITE# statement: 


PRINT#1,A$ 
PRINT#1,B$ 
PRINT#1,C$ 
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3. To access the data in the file, you must close the file and reopen it in input 
(1) mode: 


CLOSE #1 
OPEN "I",#1,"filename" 


4. Use the INPUT# or LINE INPUT# statement to read data from the 
sequential file into the program: 


INPUT#1,X$,Y3$,Z$ 


Example 1 is a short program that creates a sequential file, data, from 
information input at the terminal. 


Example 1 


10 OPEN "O", #1, "DATA" 

20 INPUT "NAME";NS 

30 IF NS="DONE" THEN END 
40 INPUT "DEPARTMENT"; DS 
50 INPUT "DATE HIRED";H$ 
60 PRINT#1,NS;","D$",";HS 
70 PRINT:GOTO 20 

RUN 

NAME? MICKEY MOUSE 
DEPARTMENT? AUDIO/VISUAL AIDS 
DATE HIRED? 01/12/72 


NAME? SHERLOCK HOLMES 
DEPARTMENT? RESEARCH 
DATE HIRED? 12/03/65 


NAME? EBENEEZER SCROOGE 
DEPARTMENT? ACCOUNTING 
DATE HIRED? 04/27/78 


NAME? SUPER MANN 
DEPARTMENT? MAINTENANCE 
DATE HIRED? 08/16/78 


NAME? DONE 
OK 


5.6 GW-BASIC User's Guide 


5.2.2 Accessing a Sequential File 


The program in Example 2 accesses the file data, created in the program in 
Example 1, and displays the name of everyone hired in 1978. 


Example 2 


10 OPEN "I", #1, "DATA" 

20 INPUT#1,NS$,D$,H$ 

30 IF RIGHTS (HS$,2)="78" THEN PRINT N$ 
40 GOTO 20 

50 CLOSE #1 

RUN 

EBENEEZER SCROOGE 

SUPER MANN 

Input past end in 20 

Ok 


The program in Example 2 reads, sequentially, every item in the file. When all 
the data has been read, line 20 causes an "Input past end" error. To avoid this 
error, insert line 15, which uses the EOF function to test for end of file: 


15 IF EOF (1) THEN END 


and change line 40 to GOTO 15. 


A program that creates a sequential file can also write formatted data to the 
diskette with the PRINT# USING statement. For example, the following 
statement could be used to write numeric data to diskette without explicit 
delimiters: 


PRINT#1, USING" ####. ##,";A,B,C,D 


The comma at the end of the format string serves to separate the items in the 
disk file. 


The LOC function, when used with a sequential file, returns the number of 128- 
byte records that have been written to or read from the file since it was opened. 
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5.2.3 Adding Data to a Sequential File 


When a sequential file is opened in O mode, the current contents are destroyed. 
To add data to an existing file without destroying its contents, open the file in 
append (A) mode. 

The program in Example 3 can be used to create, or to add onto a file called 
names. This program illustrates the use of LINE INPUT. LINE INPUT will 
read in characters until it sees a carriage retum indicator, or until it has read 255 
characters. It does not stop at quotation marks or commas. 


Example 3 


10 ON ERROR GOTO 2000 

20 OPEN "A", #1, "NAMES" 

110 REM ADD NEW ENTRIES TO FILE 
120 INPUT "NAME";NS 

130 IF NS=""" THEN 200 ‘CARRIAGE RETURN EXITS INPUT 
LOOP 

140 LINE INPUT "ADDRESS? ";A$ 
150 LINE INPUT “BIRTHDAY? ";BS 
160 PRINT#1,N$ 

170 PRINT#1,A$ 180 PRINT#1,B$ 
190 PRINT:GOTO 120 

200 CLOSE #1 

2000 ON ERROR GOTO 0 


In lines 10 and 2000 the ON ERROR GOTO statement is being used. This 
statement enables error trapping and specifies the first line (2000) of the error 
handling subroutine. Line 10 enables the error handling routine. Line 2000 
disables the error handling routine and is the point where Gw-Basic branches to 
print the error messages. 


5.3 Random Access Files 


Information in random access files is stored and accessed in distinct, numbered 
units called records. Since the information is called by number, the data can be 
called from any disk location; the program needn't read the entire disk, as when 
seeking sequential files, to locate data. Gw-Basic supports large random files. 
The maximum logical record number is 232 -1. 


5.8 
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The following statements and functions are used with random files: 


CLOSE FIELD MKI$ 

CVD LOC MKS$ 

CVI LOCK OPEN 

CVS LOF PUT 

EOF LSET/RSET UNLOCK 
ET MKD$ 

5.3.1 Creating a Random Access File 


The following program steps are required to create a random data file: 


1. 


Open the file for random access (R) mode. The following example 
specifies a record length of 32 bytes. If the record length is omitted, the 
default is 128 bytes. 

OPEN "R",#1,"filename",32 


Use the FIELD statement to allocate space in the random buffer for the 
variables that will be written to the random file: 


FIELD#1,20 AS N$,4 AS A$,8 AS P$ 


In this example, the first 20 positions (bytes) in the random file buffer are 
allocated to the string variable N$. The next 4 positions are allocated to 
AS; the next 8 to P$. 


Use LSET or RSET to move the data into the random buffer fields in left- 
or right-justified format (L=left SET;R=right SET). Numeric values must 
be made into strings when placed in the buffer. MKI$ converts an integer 
value into a string; MKS§ converts a single-precision value, and MKD$ 
converts a double-precision value. 

LSET N$=X$ LSET AS=MKS$(AMT) LSET P$=TEL$ 

Write the data from the buffer to the diskette using the PUT statement: 


PUT #1,CODE% 


The program in Example 4 takes information keyed as input at the terminal and 
writes it to a random access data file. Each time the PUT statement is executed, 
a record is written to the file. In the example, the 2-digit CODE% input in line 
30 becomes the record number. 
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Note Do not use a fielded string variable in an INPUT or LET statement. This 
causes the pointer for that variable to point into string space instead of the 
random file buffer. 


Example 4 

10 OPEN "R", #1, "INFOFILE", 32 

20 FIELD#1,20 AS NS, 4 AS AS, 8 AS P$ 
30 INPUT "2-DIGIT CODE";CODE% 

40 INPUT "NAME";XS 

50 INPUT "AMOUNT"; AMT 


60 
70 
80 
90 


INPUT "PHONE"; TELS:PRINT 
LSET N$=X$ 

LSET AS=MKSS (AMT) 

LSET P$=TEL$ 


100 PUT #1,CODE% 
110 GOTO 30 


5.3.2 Accessing a Random Access File 


The following program steps are required to access a random file: 


l. 


Open the file in R mode: 

OPEN "R",#1,"filename",32 

Use the FIELD statement to allocate space in the random buffer for the 
variables that will be read from the file: 

FIELD, #1, 20 AS N$, 4 AS A$, 8 AS P$ 


In this example, the first 20 positions (bytes) in the random file buffer are 
allocated to the string variable N$. The next 4 positions are allocated to 
A$; the next 8 to P$. 


Note Ina program that performs both INPUT and OUTPUT on the same 
random file, you can often use just one OPEN statement and one FIELD 
statement. 
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3. Use the GET statement to move the desired record into the random 
buffer: 


GET #1,CODE% 
The data in the buffer can now be accessed by the program. 


4. Convert numeric values back to numbers using the convert functions: 
CVI for integers, CVS for single-precision values, and CVD for double- 
precision values. 


PRINT NS 
PRINT CVS (A$) 


The program in Example 5 accesses the random file, infofile, that was created 
in Example 4. By inputting the 3-digit code, the information associated with 
that code is read from the file and displayed. 


Example 5 


10 OPEN "R", #1, "INFOFILE", 32 

20 FIELD #1, 20 AS NS, 4 AS AS, 8 AS P$ 
30 INPUT "2-DIGIT CODE";CODE% 

40 GET #1, CODE% 

50 PRINT NS 

60 PRINT USING "SS###.##";CVS (AS) 

70 PRINT P$:PRINT 

80 GOTO 30 


With random files, the LOC function returns the current record number. The 
current record number is the last record number used in a GET or PUT 
statement. For example, the following line ends program execution if the 
current record number in file#1 is higher than 99: 


IF LOC(1)>99 THEN END 


Example 6 is an inventory program that illustrates random file access. In this 
program, the record number is used as the part number, and it is assumed that 
the inventory will contain no more than 100 different part numbers. 

Lines 900-960 initialize the data file by writing CHR$(255) as the first 


character of each record. This is used later (line 270 and line 500) to determine 
whether an entry already exists for that part number. 
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Lines 130-220 display the different inventory functions that the program 
performs. When you type in the desired function number, line 230 branches to 
the appropriate subroutine. 


Example 6 


120 OPEN"R", #1, "INVEN.DAT", 39 

125 FIELD#1,1 AS F$,30 AS DS, 2 AS QS,2 AS RS, 
4 AS P$ 

130 PRINT:PRINT "FUNCTIONS: ":PRINT 

135 PRINT 1,"INITIALIZE FILE" 

140 PRINT 2,"CREATE A NEW ENTRY" 

150 PRINT 3,"DISPLAY INVENTORY FOR ONE PART" 

160 PRINT 4,"ADD TO STOCK" 

170 PRINT 5,"SUBTRACT FROM STOCK" 

180 PRINT 6,"DISPLAY ALL ITEMS BELOW REORDER 
LEVEL" 

220 PRINT:PRINT: INPUT"FUNCTION" ; FUNCTION 

225 IF (FUNCTION<1) OR(FUNCTION>6) THEN PRINT 
"BAD FUNCTION NUMBER":GOTO 130 

230 ON FUNCTION GOSUB 900,250,390, 480,560, 680 

240 GOTO 220 250 REM BUILD NEW ENTRY 

260 GOSUB 840 

270 IF ASC(FS) < > 255 THEN INPUT"OVERWRITE";AS: 
IF A$ < > "Y" THEN RETURN 

280 LSET FS=CHRS (0) 

290 INPUT "DESCRIPTION"; DESCS 

300 LSET DS=DESCS$ 310 INPUT "QUANTITY IN STOCK"; 
Q% 

320 LSET QS=MKIS$ (Q%) 

330 INPUT "REORDER LEVEL";R% 

340 LSET RS=MKI$ (R$) 

350 INPUT "UNIT PRICE";P 

360 LSET PS=MKSS (P) 

370 PUT#1,PART% 

380 RETURN 

390 REM DISPLAY ENTRY 

400 GOSUB 840 

410 IF ASC(FS)=255 THEN PRINT "NULL ENTRY": 
RETURN 

420 PRINT USING "PART NUMBER ###";PARTS 

430 PRINT D$ 
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440 
450 
460 
470 
480 
490 
500 


510 
520 
530 
540 
550 
560 
570 
580 


590 
600 
610 
620 


630 
640 
Q%; 
650 
660 
670 
680 
690 
710 
720 


730 
740 
840 
850 


890 
900 
910 


PRINT USING “QUANTITY ON HAND #####"; CVI (QS) 
PRINT USING "REORDER LEVEL #####";CVI (RS) 
PRINT USING "UNIT PRICE SS##.##"; CVS (PS) 
RETURN 

REM ADD TO STOCK 

GOSUB 840 

IF ASC(F$)=255 THEN PRINT "NULL ENTRY": 
RETURN 

PRINT DS: INPUT "QUANTITY TO ADD";A% 
Q%=CVI (Q$) +A% 

LSET QS=MKI$ (Q%) 

PUT#1,PART% 


RETURN 

REM REMOVE FROM STOCK 

GOSUB 840 

IF ASC(F$)=255 THEN PRINT “NULL ENTRY": 


RETURN 


PRINT D$ 

INPUT “QUANTITY TO SUBTRACT"; S% 

Q%=CVI (QS) 

IF (Q%-S%)<O THEN PRINT "“ONLY";Q%;" IN 


STOCK" :GOTO 600 

Q%=0%-S% 

IF Q%= < CVI(R$) THEN PRINT "QUANTITY NOW"; 
"REORDER LEVEL"; CVI (R$) 

LSET Q$=MKIS$ (Q%) 

PUT#1,PART% 

RETURN 

REM DISPLAY ITEMS BELOW REORDER LEVEL4 

FOR I=1 TO 100 

GET#1,I1 

IF CVI (Q$)<CVI(RS$) THEN PRINT D$;" QUANTITY"; 
CVI (Q$) TAB(50) “REORDER LEVEL"; 

CVI (R$) 

NEXT I 

RETURN 

INPUT "PART NUMBER"; PARTS 

IF (PART% < 1)OR(PART% > 100) THEN PRINT "BAD 
PART NUMBER": GOTO 840 ELSE GET#1, PARTS: 
RETURN 

END 

REM INITIALIZE FILE 

INPUT "ARE YOU SURE";BS$:IF B$ < > "Y" THEN 
RETURN 


920 
930 
940 
950 
960 


LSET FS=CHR$ (255) 
FOR I=1 TO 100 
PUT#1,I 

NEXT I 

RETURN 


Creating and Using Files 5.13 


6 Constants, Variables, 
Expressions and Operators 


6.1 Constants 6.3 

6.1.1 Single- and Double-Precision Form for Numeric 
Constants 6.4 

6.2 Variables 6.5 

6.2.1 Variable Names and Declarations 6.5 

6.2.2 Type Declaration Characters 6.5 

6.2.3 Array Variables 6.6 

6.2.4 Memory Space Requirements for Variable Storage 6.7 

6.3 Type Conversion 6.8 

6.4 Expressions and Operators 6.10 

6.4.1 Arithmetic Operators 6.10 

6.4.1.1 Integer Division and Modulus Arithmetic 6.11 

6.4.1.2 Overflow and Division by Zero 6.12 

6.4.2 Relational Operators 6.13 

6.4.3 Logical Operators 6.13 

6.4.4 Functional Operators 6.15 


6.4.5 String Operators 6.15 


Constants, Variables, Expressions and Operators 6.3 


After you have learned the fundamentals of programming in Gw-sasic, you will 
find that you will want to write more complex programs. The information in 
this chapter will help you learn more about the use of constants, variables, 
expressions, and operators in Gw-Basic, and how they can be used to develop 
more sophisticated programs. 


6.1 Constants 


Constants are static values the cw-sasic Interpreter uses during execution of 
your program. There are two types of constants: string and numeric. 


A string constant is a sequence of 0 to 255 alphanumeric characters enclosed in 
double quotation marks. The following are sample string constants: 


"HELLO" 
"$25,000.00" 
"Number of Employees" 


Numeric constants can be positive or negative. When entering a numeric 
constant in Gw-Basic, you should not type the commas. For instance, if the 
number /0,000 were to be entered as a constant, it would be typed as 10000. 
There are five types of numeric constants: integer, fixed-point, floating-point, 
hexadecimal, and octal. 


Constant Description 

Integer Whole numbers between -32768 and +32767. They 
do not contain decimal points. 

Fixed-Point Positive or negative real numbers that contain decimal 
points. 

Floating-Point Positive or negative numbers represented 

Constants in exponential form (similar to scientific notation). A 


floating-point constant consists of an optionally- 
signed integer or fixed-point number (the mantissa), 
followed by the letter E and an optionally-signed 
integer (the exponent). 
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The allowable range for floating-point constants is 
3.0X10 -39 to 1.7X10 38. For example: 


235.988E-7=.0000235988 
2359E6=2359000000 


Hexadecimal Hexadecimal numbers with prefix &H. For example: 


&H76 
&H32F 


Octal Octal numbers with the prefix &O or &. For example: 


&0347 
& 1234 


6.1.1 Single- and Double-Precision Form for Numeric 
Constants 


Numeric constants can be either integers, single-precision or double-precision 
numbers. Integer constants are stored as whole numbers only. Single-precision 
numeric constants are stored with 7 digits (although only 6 may be accurate). 
Double-precision numeric constants are stored with 17 digits of precision, and 
printed with as many as 16 digits. 


A single-precision constant is any numeric constant with either 


e seven or fewer digits 
e exponential form using E 
e a trailing exclamation point (!) 


A double-precision constant is any numeric constant with either 


e eight or more digits 
e exponential form using D 


e  atrailing number sign (#) 
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The following are examples of single- and double-precision numeric constants: 


Single-Precision Constants Double-Precision Constants 
46.8 345692811 

-1.09E-06 -1.09432D-06 

3489.0 3490.0# 

22.5! 7654321.1234 


6.2 Variables 


Variables are the names that you have chosen to represent values used in a Gw- 
BASIC program. The value of a variable may be assigned specifically, or may be 
the result of calculations in your program. If a variable is assigned no value, 
GW-BASIc assumes the variable’s value to be zero. 


6.2.1 Variable Names and Declarations 


GW-BASIC variable names may be any length; up to 40 characters are significant. 
The characters allowed in a variable name are letters, numbers, and the decimal 
point. The first character in the variable name must be a letter. Special type 
declaration characters are also allowed. 


Reserved words (all the words used as Gw-Basic commands, statements, 
functions, and operators) can’t be used as variable names. However, if the 
reserved word is embedded within the variable name, it will be allowed. 


Variables may represent either numeric values or strings. 


6.2.2 Type Declaration Characters 


Type declaration characters indicate what a variable represents. The following 
type declaration characters are recognized: 
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Character Type of Variable 
$ String variable 
% Integer variable 


! Single-precision variable 


# Double-precision variable 


The following are sample variable names for each type: 


Variable Type Sample Name 
String variable N$ 

Integer variable LIMIT% 
Single-precision variable MINIMUM! 
Double-precision variable Pl# 


The default type for a numeric variable name is single-precision. Double- 
precision, while very accurate, uses more memory space and more calculation 
time. Single-precision is sufficiently accurate for most applications. However, 
the seventh significant digit (if printed) will not always be accurate. You should 
be very careful when making conversions between integer, single-precision, 
and double-precision variables. 


The following variable is a single-precision value by default: 
ABC 


Variables beginning with FN are assumed to be calls to a user-defined function. 


The Gw-Basic statements DEFINT, DEFSTR, DEFSNG, and DEFDBL may be 
included in a program to declare the types of values for certain variable names. 


6.2.3 Array Variables 


An array is a group or table of values referenced by the same variable name. 
Each element in an array is referenced by an array variable that is a subscripted 
integer or an integer expression. The subscript is enclosed within parentheses. 
An array variable name has as many subscripts as there are dimensions in the 
array. 
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For example, 

V(10) 

references a value in a one-dimensional array, while 
T(1,4) 


references a value in a two-dimensional array. 


The maximum number of dimensions for an array in cw-sasic is 255. The 
maximum number of elements per dimension is 32767. 


Note If you are using an array with a subscript value greater than 10, you 
should use the DIM statement. Refer to the GW-BASIC User's Reference for 
more information. If a subscript greater than the maximum specified is used, 
you will receive the error message "Subscript out of range.” 


Multidimensional arrays (more than one subscript separated by commas) are 
useful for storing tabular data. For example, A(1,4) could be used to represent a 
two-row, five-column array such as the following: 


Column 0 1 2 3 4 
Row 0 10 20 30 40 50 
Row 1 60 70 80 90 100 


In this example, element A(1,2)=80 and A(0,3)=40. 


Rows and columns begin with 0, not 1, unless otherwise declared. For more 
information, see the OPTION BASE statement in the GW-BASIC User's 
Reference. 


6.2.4 Memory Space Requirements for Variable 
Storage 


The different types of variables require different amounts of storage. 
Depending on the storage and memory capacity of your computer and the size 
of the program that you are developing, these can be important considerations. 
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Variable Required Bytes of Storage 
Integer 2 

Single-precision 4 

Double-precision 8 

Arrays Required Bytes of Storage 
Integer 2 per element 
Single-precision 4 per element 
Double-precision 8 per element 

Strings: 


Three bytes overhead, plus the present contents of the string as one byte for 
each character in the string. Quotation marks marking the beginning and end of 
each string are not counted. 


6.3 Type Conversion 


When necessary, GW-BASIC converts a numeric constant from one type of 
variable to another, according to the following rules: 


If a numeric constant of one type is set equal to a numeric variable of a 
different type, the number is stored as the type declared in the variable 
name. For example: 


10 A% = 23.42 
20 PRINT A5 
RUN 

23 


If a string variable is set equal to a numeric value or vice versa, a "Type 
Mismatch” error occurs. 


During an expression evaluation, all of the operands in an arithmetic or 
relational operation are converted to the same degree of precision; that is, 
that of the most precise operand. Also, the result of an arithmetic 
operation is returned to this degree of precision. For example: 
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10 D# = 6#/7 

20 PRINT D# 

RUN 
~-8571428571428571 


The arithmetic is performed in double-precision, and the result is returned 
in D# as a double-precision value. 


10 D = 6#/7 
20 PRINT D 
RUN 


The arithmetic is performed in double-precision, and the result is returned 
to D (single-precision variable) rounded and printed as a single-precision 
value. 

Logical operators convert their operands to integers and return an integer 
result. Operands must be within the range of -32768 to 32767 or an 
"Overflow" error occurs. 


When a floating-point value is converted to an integer, the fractional 
portion is rounded. For example: 


10 C% = 55.88 
20 PRINT C% 
RUN 

56 


If a double-precision variable is assigned a single-precision value, only 
the first seven digits (rounded), of the converted number are valid. This is 
because only seven digits of accuracy were supplied with the 
singleprecision value. The absolute value of the difference between the 
printed double-precision number, and the original single-precision value, 
is less than 6.3E-8 times the original single-precision value. For example: 


10 A = 2.04 
20 BE =A 
30 PRINT A; Bt 
RUN 
2.04 2.039999961853027 
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6.4 Expressions and Operators 


An expression may be simply a string or numeric constant, a variable, or it may 
combine constants and variables with operators to produce a single value. 


Operators perform mathematical or logical operations on values. The operators 
provided by cw-sasic are divided into four categories: 


° Arithmetic 
e Relational 
e Logical 


° Functional 


6.4.1 Arithmetic Operators 


The following are the arithmetic operators recognized by cw-sasic. They appear 
in order of precedence. 
Operator Operation 
A Exponentiation 
- Negation 
* Multiplication 
/ Floating-point Division 
+ Addition 
Subtraction 
Operations within parentheses are performed first. Inside the parentheses, the 
usual order of precedence is maintained. 
The following are sample algebraic expressions and their Gw-Basic counterparts: 
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Algebraic BASIC 

Expression Expression 

X-Z (X-Y)/Z 
Y 

XY X*Y/Z 

Z 

X+¥ (X+Y)/Z 
Z 

(X2)y (XA2 AY 

XyZ XA(YAZ) 

X(-Y) X*(-Y) 


Two consecutive operators must be separated by parentheses. 


6.4.1.1 Integer Division and Modulus Arithmetic 


Two additional arithmetic operators are available: integer division and modulus 
arithmetic. 


Integer division is denoted by the backslash (\). The operands are rounded to 
integers (must be within the range of -32768 to 32767) before the division is 
performed, and the quotient is truncated to an integer. 


The following are examples of integer division: 


10\4 = 2 

25.68\6.99 = 3 

In the order of occurrence within Gw-sasic, the integer division will be 
performed just after floating-point division. 


Modulus arithmetic is denoted by the operator MOD. It gives the integer value 
that is the remainder of an integer division. 


The following are examples of modulus arithmetic: 


10.4 MOD 4 = 2 
(10/4=2 with a remainder 2) 


25.68 MOD 6.99 = 5 
(26/7=3 with a remainder 5) 
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In the order of occurrence within Gw-Basic modulus arithmetic follows integer 
division. The INT and FIX functions, described in the GW-BASIC User's 
Reference, are also useful in modulus arithmetic. 


6.4.1.2 Overflow and Division by Zero 


If, during the evaluation of an expression, a division by zero is encountered, the 
"Division by zero" error message appears, machine infinity with the sign of the 
numerator is supplied as the result of the division, and execution continues. 

If the evaluation of an exponentiation results in zero being raised to a negative 
power, the "Division by Zero” error message appears, positive machine infinity 
is supplied as the result of the exponentiation, and execution continues. 

If overflow occurs, the "Overflow" error message appears, machine infinity 
with the algebraically correct sign is supplied as the result, and execution 
continues. The errors that occur in overflow and division by zero will not be 
trapped by the error trapping function. 


6.4.2 Relational Operators 


Relational operators let you compare two values. The result of the comparison 
is either true (-1) or false (0). This result can then be used to make a decision 
regarding program flow. 


Table 6.1 displays the relational operators. 


Table 6.1 
Relational Operators 


Operator Relation Tested Expression 
= Equality X=Y 

> Inequality XoY 

< Less than X<Y 

> Greater than X>Y 

<= Less than or equal to X<=Y 

>= Greater than or equal to X>=Y 
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The equal sign is also used to assign a value to a variable. See the LET 
statement in the GW-BASIC User's Reference. 

When arithmetic and relational operators are combined in one expression, the 
arithmetic is always performed first: 


X+Y < (T-1)/Z 


This expression is true if the value of X plus Y is less than the value of T-1 
divided by Z. 


6.4.3 Logical Operators 


Logical operators perform tests on multiple relations, bit manipulation, or 
boolean operations. The logical operator returns a bit-wise result which is either 
true (not zero) or false (zero). In an expression, logical operations are 
performed after arithmetic and relational operations. The outcome of a logical 
operation is determined as shown in the following table. The operators are 
listed in order of precedence. 


Table 6.2 
Results Returned by Logical Operations 
Operation Value Value Result 
NOT X NOT X 
T F 
F T 
AND X Y X AND Y 
T T T 
T F F 
F T F 
F F F 
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Table 6.2 (continued) 
Operation Value 
OR 


N 
N 
a 
Ls) 
a 
= 
toy 


XOR 


EQV 


THs x TAA K DAA x NNSA x 
THII <Á TAMA K Dans K WH « 
>s 
m 
QO 
< 
-< 


Just as the relational operators can be used to make decisions regarding 
program flow, logical operators can connect two or more relations and return a 
true or false value to be used in a decision. For example: 


IF D<200 AND F<4 THEN 80 
IF I>10 OR K<0 THEN 50 
IF NOT P THEN 100 


Logical operators convert their operands to 16-bit, signed, two’s complement 
integers within the range of -32768 to +32767 (if the operands are not within 
this range, an error results). If both operands are supplied as 0 or -1, 
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logical operators return 0 or -1. The given operation is performed on these 
integers in bits; that is, each bit of the result is determined by the corresponding 
bits in the two operands. 


Thus, it is possible to use logical operators to test bytes for a particular bit 
pattern. For instance, the AND operator may be used to mask all but one of the 
bits of a status byte at a machine I/O port. The OR operator may be used to 
merge two bytes to create a particular binary value. The following examples 
demonstrate how the logical operators work: 


Example Explanation 

63 AND 16=16 63 = binary 111111 and 16 = binary 10000, so 63 
AND 16 = 16 

15 AND 14=14 15 = binary 1111 and 14 = binary 1110, so 15 AND 
14 = 14 (binary 1110) 

-1 AND 8=8 -1 = binary 1111111111111111 and 8 = binary 1000, 
so -1 AND 8=8 

4 OR 2=6 4 = binary 100 and 2 = binary 10, so4 OR 2 = 6 
(binary 110) 

10 OR 10=10 10 = binary 1010, so 1010 OR 1010 =1010 (10) 

-1 OR -2=-1 -] = binary 1111111111111111 and -2 = binary 


1111111111111110,so -1 OR -2 = -1. The bit 
complement of 16 zeros is 16 ones, which is the two’s 
complement representation of -1. 

NOT X=-(X+1) The two’s complement of any integer is the bit 
complement plus one. 


6.4.4 Functional Operators 


A function is used in an expression to call a predetermined operation that is to 
be performed on an operand. cw-sasic has intrinsic functions that reside in the 
system, such as SQR (square root) or SIN (sine). 


GW-BASIC also allows user-defined functions written by the programmer. See the 
DEF FN statement in the GW-BASIC User's Reference. 
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6.4.5 String Operators 


To compare strings, use the same relational operators used with numbers: 


Operator Meaning 

= Equal to 

<> Unequal 

< Less than 

> Greater than 

<= Less than or equal to 
>= Greater than or equal to 


The cw-sasic Interpreter compares strings by taking one character at a time 
from each string and comparing their asci codes. If the ascn codes in each 
string are the same, the strings are equal. If the ascu codes differ, the lower 
code number will precede the higher code. If the interpreter reaches the end of 
one string during string comparison, the shorter string is said to be smaller, 
providing that both strings are the same up to that point. Leading and trailing 
blanks are significant. 


For example: 


"AA" < "AB" 

"FILENAME" = "FILENAME" 

"ye" > "xg" 

NGL. a noii 

"kg" > "KG" 

"SMYTH" < "SMYTHE" 

B$ < "9/12/78" where B$ = "8/12/78" 


String comparisons can also be used to test string values or to alphabetize 
strings. All string constants used in comparison expressions must be enclosed 
in quotation marks. 


Strings can be concatenated by using the plus (+) sign. For example: 


10 A$="FILE":BS="NAME" 
20 PRINT A$+B$ 

30 PRINT "NEW " + AS+B$ 
RUN 

FILENAME 

NEW FILENAME 


Appendix A 
Error Codes and Messages 


Code: Message: 
1 NEXT without FOR 


NEXT statement does not have a corresponding FOR statement. 
Check variable at FOR statement for a match with the NEXT 
statement variable. 


2 Syntax error 


A line is encountered that contains an incorrect sequence of 
characters (such as unmatched parentheses, a misspelled 
command or statement, incorrect punctuation). This error causes 
GW-BASIC to display the incorrect line in edit mode. 


3 RETURN without GOSUB 


A RETURN statement is encountered for which there is no 
previous GOSUB statement. 


4 Out of DATA 


A READ statement is executed when there are no DATA 
statements with unread data remaining in the program. 


5 Illegal function call 


An out-of-range parameter is passed to a math or string function. 
An illegal function call error may also occur as the result of 


e anegative or unreasonably large subscript 
e  anegative or zero argument with LOG 
e anegative argument to SQR 


è anegative mantissa with a noninteger power 
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10 


11 


e acall to a USR function for which the starting address has 
not yet been given 


e an improper argument to MID$, LEFT$, RIGHTS, INP, 
OUT, WAIT, PEEK, POKE, TAB, SPC, STRINGS, 
SPACES, INSTR, or ON...GOTO 


Overflow 


The result of a calculation is too large to be represented in GW- 
BASIC’s number format. If underflow occurs, the result is zero, 
and execution continues without an error. 


Out of memory 


A program is too large, has too many FOR loops, GOSUBs, 
variables, or expressions that are too complicated. Use the 
CLEAR statement to set aside more stack space or memory 
area. 


Undefined line number 


A line reference in a GOTO, GOSUB, IF-THEN...ELSE, or 
DELETE is a nonexistent line. 


Subscript out of range 

An array element is referenced either with a subscript that is 
outside the dimensions of the array, or with the wrong number 
of subscripts. 


Duplicate Definition 


Two DIM statements are given for the same array, or a DIM 
statement is given for an array after the default dimension of 10 
has been established for that array. 

Division by zero 

A division by zero is encountered in an expression, or the 
operation of involution results in zero being raised to a negative 
power. Machine infinity with the sign of the numerator is 
supplied as the result of the division, or positive machine 
infinity is supplied as the result of the involution, and execution 
continues. 


12 


13 


14 


15 


16 


17 


18 


19 


Error Codes and Messages A.3 


Illegal direct 


A Statement that is illegal in direct mode is entered as a direct 
mode command. 


Type mismatch 


A string variable name is assigned a numeric value or vice 
versa; a function that expects a numeric argument is given a 
string argument or vice versa. 


Out of string space 


String variables have caused cw-basic to exceed the amount of 
free memory remaining. Gw-BAsic allocates string space 
dynamically until it runs out of memory. 


String too long 


An attempt is made to create a string more than 255 characters 
long. 


String formula too complex 


A string expression is too long or too complex. Break the 
expression into smaller expressions. 


Can’t continue 

An attempt is made to continue a program that 

e has halted because of an error 

e has been modified during a break in execution 
e does not exist 

Undefined user function 


A USR function is called before the function definition (DEF 
statement) is given. 


No RESUME 


An error-trapping routine is entered but contains no RESUME 
statement. 
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20 


21 


22 


23 


24 


25 


26 


27 


28 


29 


RESUME without error 


A RESUME statement is encountered before an error-trapping 
routine is entered. 


Unprintable error 


No error message is available for the existing error condition. 
This is usually caused by an error with an undefined error code. 


Missing operand 

An expression contains an operator with no operand following 
1t. 

Line buffer overflow 

An attempt is made to input a line that has too many characters. 
Device Timeout 


GW-BASIC did not receive information from an I/O device 
within a predetermined amount of time. 


Device Fault 

Indicates a hardware error in the printer or interface card. 
FOR Without NEXT 

A FOR was encountered without a matching NEXT. 
Out of Paper 

The printer is out of paper; or, a printer fault. 
Unprintable error 


No error message is available for the existing error condition. 
This is usually caused by an error with an undefined error code. 


WHILE without WEND 
A WHILE statement does not have a matching WEND. 


30 


31-49 


50 


51 


52 


53 


54 


55 


56 


Error Codes and Messages A.5 


WEND without WHILE 
A WEND was encountered without a matching WHILE. 
Unprintable error 


No error message is available for the existing error condition. 
This is usually caused by an error with an undefined error code. 


FIELD overflow 

A FIELD statement is attempting to allocate more bytes than 
were specified for the record length of a random file. 
Internal error 

An internal malfunction has occurred in cw-nasic. Report to 
your dealer the conditions under which the message appeared. 
Bad file number 


A statement or command references a file with a file number 
that is not open or is out of range of file numbers specified at 
initialization. 

File not found 

A LOAD, KILL, NAME, FILES, or OPEN statement references 
a file that does not exist on the current diskette. 

Bad file mode 

An attempt is made to use PUT, GET, or LOF with a sequential 
file, to LOAD arandom file, or to execute an OPEN with a file 
mode other than I, O, A, or R. 

File already open 

A sequential output mode OPEN is issued for a file that is 
already open, or a KILL is given for a file that is open. 
Unprintable error 

An error message is not available for the error condition which 
exists. This is usually caused by an error with an undefined 
error code. 
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57 


58 


59-60 


61 


62 


63 


64 


65 


66 


Device I/O Error 


Usually a disk I/O error, but generalized to include all I/O 
devices. It is a fatal error; that is, the operating system cannot 
recover from the error. 

File already exists 


The filename specified in a NAME statement is identical to a 
filename already in use on the diskette. 


Unprintable error 


No error message is available for the existing error condition. 
This is usually caused by an error with an undefined error code. 


Disk full 
All disk storage space is in use. 
Input past end 


An INPUT statement is executed after all the data in the file has 
been input, or for a null (empty) file. To avoid this error, use the 
EOF function to detect the end of file. 


Bad record number 


In a PUT or GET statement, the record number is either greater 
than the maximum allowed (16,777,215) or equal to zero. 


Bad filename 


An illegal form is used for the filename with LOAD, SAVE, 
KILL, or OPEN; for example, a filename with too many 
characters. 


Unprintable error 


No error message is available for the existing error condition. 
This is usually caused by an error with an undefined error code. 


Direct statement in file 


A direct statement is encountered while loading a ascu-format 
file. The LOAD is terminated. 


67 


68 


69 


70 


Error Codes and Messages A.7 


Too many files 


An attempt is made to create a new file (using SAVE or OPEN) 
when all directory entries are full or the file specifications are 
invalid. 

Device Unavailable 

An attempt is made to open a file to a nonexistent device. It 
may be that hardware does not exist to support the device, such 
as Ipt2: or Ipt3:, or is disabled by the user. This occurs if an 
OPEN "COMI: statement is executed but the user disables 
RS232 support with the /c: switch directive on the command 
line. 


Communication buffer overflow 


Occurs when a communications input statement is executed, but 
the input queue is already full. Use an ON ERROR GOTO 
statement to retry the input when this condition occurs. 
Subsequent inputs attempt to clear this fault unless characters 
continue to be received faster than the program can process 
them. In this case several options are available: 


e — Increase the size of the COM receive buffer with the /c: 
switch. 


e Implement a hand-shaking protocol with the host/satellite 
(such as: XON/XOFF, as demonstrated in the TTY 
programming example) to turn transmit off long enough to 
catch up. 


e Use a lower baud rate for transmit and receive. 
Permission Denied 


This is one of three hard disk errors returned from the diskette 
controller. 


èe An attempt has been made to write onto a diskette that is 
write protected. 


e Another process has attempted to access a file already in 
use. 

e The UNLOCK range specified does not match the 
preceding LOCK statement. 
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71 


72 


73 


74 


75 


76 


Disk not Ready 

Occurs when the diskette drive door is open or a diskette is not 
in the drive. Use an ON ERROR GOTO statement to recover. 
Disk media error 


Occurs when the diskette controller detects a hardware or media 
fault. This usually indicates damaged media. Copy any existing 
files to a new diskette, and reformat the damaged diskette. 
FORMAT maps the bad tracks in the file allocation table. The 
remainder of the diskette is now usable. 


Advanced Feature 

An attempt was made to use a reserved word that is not available 
in this version of GW-BASIC. 

Rename across disks 

Occurs when an attempt is made to rename a file to a new name 
declared to be on a disk other than the disk specified for the old 
name. The naming operation is not performed. 

Path/File Access Error 

During an OPEN, MKDIR, CHDIR, or RMDIR operation, MS- 
DOS is unable to make a correct path-to-filename connection. 
The operation is not completed. 

Path not found 

During an OPEN, MKDIR, CHDIR, or RMDIR operation, MS- 
DOS is unable to find the path specified. The operation is not 
completed. 


Appendix B 
Mathematical Functions 


Mathematical functions not intrinsic to Gw-BAsic can be calculated as follows: 


Function 
Secant 
Cosecant 
Cotangent 
Inverse Sine 


Inverse 
Cosine 


Inverse 
Secant 


Inverse 
Cosecant 


Inverse 
Cotangent 


Hyperbolic 
Sine 
Hyperbolic 
Cosine 


Hyperbolic 
Tangent 
Hyperbolic 
Secant 


Hyperbolic 
Cosecant 


Hyperbolic 
Cotangent 


GW-BASIC Equivalent 
SEC(X)=1/COS(X) 

CSC{(X)=1/SIN®} 

COTQQ=1/TANQO 
ARCSIN(X}=ATN(X/SQR(-X*X+1)) 
ARCCOS(X)=ATN (X/SQR(-X*X+1))}+ 11/2 


ARCSEC(X)=ATN(X/SQR(X*X-1))+SGN(SGN(X)-1)* 1/72 
ARCCSC(X)=ATN(X/SQR(X*X-1))+SGN(X)-1)* 71/2 
ARCCOT(X)=ATN(X)+ 14/2 

SINH(X)=(EXP(X)}- EXP(-X))/2 
COSH(X)=EXP(X)+EXP(-X))/2] 
TANH(X)=EXP(X)-EXP(-X) /+(EXP(X)+EXP(-X)) 
SECH(X)=2/((EXP(X)+EXP(-X)) 
CSCH(X)=2/(EXP(X)-EXP{-X)) 


COTH(X)=EXP{-X)(EXP(X)-EXP(-X))*2+1 
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Inverse 
Hyperbolic 
Sine 
Inverse 
Hyperbolic 
Cosine 


Inverse 
Hyperbolic 
Tangent 
Inverse 
Hyperbolic 


Cosecant 


Inverse 
Hyperbolic 
Secant 


Inverse 
Hyperbolic 
Cotangent 


ARCSINH(X)=LOG(X/SQR(X*X+1)) 


ARCCOSH(X)=LOG(X+SQR(X*X-1)) 


ARCTANH(X)=LOG((1+X)/(1-X) 2 


ARCCSCH(X)=LOG(SGN(X)*SQR(X*X+1)+1)/X 


ARCSECH(X)=LOG(SQR(-X*X+1)+1)/X 


ARCCOTH(X)=LOG((X+1)/(X-1))/2 


Appendix C 


ASCII Character Codes 


Dec 


000 
001 
002 
003 
004 
005 
006 
007 
008 
009 
010 
011 
012 
013 
014 
015 
016 
017 
018 
019 
020 
021 
022 
023 
024 
025 


Dec=Decimal, Oct=Octal, Hex=Hexadecimal(H), Chr=Character, LF=Line feed 
FF=Form feed, CR=Camiage retum, DEL=Rubout 


Oct 


000 
001 
002 
003 
004 
005 
006 
007 
010 
011 
012 
013 
014 
015 
016 
017 
020 
021 
022 
023 
024 
025 
026 
027 
030 
031 


Hex 


00H 
01H 
02H 
03H 
04H 
05H 
06H 
07H 
08H 
09H 
OAH 
OBH 
OCH 
O0DH 
OEH 
OFH 
10H 
11H 
12H 
13H 
14H 
15H 
16H 
17H 
18H 
19H 


Chr 


NUL 
SOH 
STX 
ETX 
EOT 
ENQ 
ACK 
BEL 
BS 
HT 
LF 
VT 
FF 
CR 
SO 
SI 
DLE 
DC1 
DC2 
DC3 
DC4 
NAK 
SYN 
ETB 
CAN 
EM 


Dec 


032 
033 
034 
035 
036 
037 
038 
039 
040 
041 
042 
043 
044 
045 
046 
047 
048 
049 
050 
051 
052 
053 
054 
055 
056 
057 


28H 
29H 
2AH 
2BH 
2CH 
2DH 
2EH 
2FH 
30H 
31H 
32H 
33H 
34H 
35H 
36H 
37H 
38H 
39H 


Chr 
SP 


+ Sn pRa 


O oNDTDUARARUNEeON: 
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Dec 


026 
027 
028 
029 
030 
031 
064 
065 
066 
067 
068 
069 
070 
071 
072 
073 
074 
075 
076 
077 
078 
079 
080 
081 
082 
083 
084 
085 
086 
087 
088 
089 
090 
091 
092 
093 
094 
095 


Dec=Decimal, Oct=Octal, Hex=Hexadecimal(H), Chr=Character, LF=Line feed 
FF=Form feed, CR=Carriage retum, DEL=Rubout 


Oct 


032 
033 
034 
035 
036 
037 
100 
101 
102 
103 
104 
105 
106 
107 
110 
111 
112 
113 
114 
115 
116 
117 
120 
121 
122 
123 
124 
125 
126 
127 
130 
131 
132 
133 
134 
135 
136 
137 


Hex 


1AH 
1BH 
1CH 
1DH 
1EH 
1FH 
40H 
41H 
42H 
43H 
44H 
45H 
46H 
47H 
48H 
49H 
4AH 
4BH 
4CH 
4DH 
4EH 
4FH 
50H 
51H 
52H 
53H 
54H 
55H 
56H 
57H 
58H 
59H 
SAH 
SBH 
SCH 
SDH 
SEH 
SFH 


Chr 
SUB 
ESC 
FS 
GS 
RS 


Cc 
n 


PT OTNKKE<KCAIYAOVOZZOAM-““ZTOAMMONDFS®© 


Dec 


058 
059 
060 
061 
062 
063 
096 
097 
098 
099 
100 
101 
102 
103 
104 
105 
106 
107 
108 
109 
110 
111 
112 
113 
114 
115 
116 
117 
118 
119 
120 
121 
122 
123 
124 
125 
126 
127 


Oct 


072 
073 
074 
075 
076 
077 
140 
141 
142 
143 
144 
145 
146 
147 
150 
151 
152 
153 
154 
155 
156 
157 
160 
161 
162 
163 
164 
165 
166 
167 
170 
171 
172 
173 
174 
175 
176 
177 


Hex 


3AH 
3BH 
3CH 
3DH 
3EH 
3FH 
60H 
61H 
62H 
63H 
64H 
65H 
66H 
67H 
68H 
69H 
6AH 
6BH 
6CH 
6DH 
6EH 
6FH 
70H 
71H 
72H 
73H 
74H 
75H 
76H 
77H 
78H 
79H 
7AH 
7BH 
7CH 
7DH 
7EH 
7FH 


Chr 


"SV Aann 


L= One Re ee ALS nona Say Se oe re oo 


DEL 


Appendix D 
Assembly Language 
(Machine Code) Subroutines 


This appendix is written primarily for users experienced in assembly language 
programming. 

Gw-BAsic lets you interface with assembly language subroutines by using the 
USR function and the CALL statement. 


The USR function allows assembly language subroutines to be called in the 
same way Gw-BASIC intrinsic functions are called. However, the CALL statement 
is recommended for interfacing machine language programs with Gw-sasic. The 
CALL statement is compatible with more languages than the USR function 
call, produces more readable source code, and can pass multiple arguments. 


D.1 Memory Allocation 


Memory space must be set aside for an assembly language (or machine code) 
subroutine before it can be loaded. There are three recommended ways to set 
aside space for assembly language routines: 


e Specify an array and use VARPTR to locate the start of the array before 
every access. 


e Use the /m switch in the command line. Get Gw-Basic’s Data segment 
(DS), and add the size of DS to reference the reserved space above the 
data segment. 


e Execute a .COM file that stays resident, and store a pointer to it in an 
unused interrupt vector location. 


There are three recommended ways to load assembly language routines: 
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e BLOAD the file. Use DEBUG to load in an .EXE file that is in high 
memory, run Gw-sasic, and BSAVE the .EXE file. 


e Execute a .COM file that contains the routines. Save the pointer to these 
routines in unused interrupt-vector locations, so that your application in 
GW-BASIC can get the pointer and use the routine(s). 

e Place the routine into the specified area. 

If, when an assembly language subroutine is called, more stack space is needed, 

GW-BASIC stack space can be saved, and a new stack set up for use by the 

assembly language subroutine. The cw-sasic stack space must be restored, 

however, before returning from the subroutine. 


D.2 CALL Statement 


CALL variablename[(arguments)] 


variablename contains the offset in the current segment of the subroutine being 
called. 


arguments are the variables or constants, separated by commas, that are to be 
passed to the routine. 


For each parameter in arguments, the 2-byte offset of the parameter’s location 
within the data segment (DS) is pushed onto the stack. 


The Gw-sasic return address code segment (CS), and offset (IP) are pushed onto 
the stack. 


A long call to the segment address given in the last DEF SEG statement and the 
offset given in variablename transfers control to the user’s routine. 


The stack segment (SS), data segment (DS), extra segment (ES), and the stack 
pointer (SP) must be preserved. 
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Figure D.1 shows the state of the stack at the time of the CALL statement: 


High Addresses Parameter 0 Each parameter is a 2-byte 
Parameter 1 pointer into memory 


Parameter n 


Return Segment Address 


Return Offset «— Stack Pointer 


Low Addresses 





Figure D.1 Stack Layout When the CALL Statement is Activated 


The user’s routine now has control. Parameters may be referenced by moving 
the stack pointer (SP) to the base pointer (BP) and adding a positive offset to 
BP. 


Upon entry, the segment registers DS, ES, and SS all point to the address of the 
segment that contains the Gw-Basic interpreter code. The code segment register 
CS contains the latest value supplied by DEF SEG. If no DEF SEG has been 
specified, it then points to the same address as DS, ES, and SS (the default DEF 
SEG). 
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Figure D.2 shows the condition of the stack during execution of the called 
subroutine: 


High Addresses Parameter 0 «— Absent if any parameter is 
Parameter 1 referenced within a nested 
procedure 


Parameter n 


Return Segment Address |«—— Absent in Local Procedure 






Return Offset +— Stack Pointer 
Old Stack Marker <«— New Stack Marker 
Local Variables +— Only in re-entrant 
procedure 
This space may be used +— Stack pointer may change 
during procedure execution during procedure execution 


Low Addresses 


Figure D.2 Stack Layout During Execution of a CALL Statement 


The following seven rules must be observed when coding a subroutine: 


1. The called routine may destroy the contents of the AX, BX, CX, DX, SI, 
DI, and BP registers. They do not require restoration upon return to Gw- 
BASIC. However, all segment registers and the stack pointer must be 
restored. Good programming practice dictates that interrupts enabled or 
disabled be restored to the state observed upon entry. 
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2. The called program must know the number and length of the parameters 
passed. References to parameters are positive offsets added to BP, 
assuming the called routine moved the current stack pointer into BP; that 
is, MOV BP,SP. When 3 parameters are passed, the location of PO is at 
BP+10, P1 is at BP+8, and P2 is at BP+6. 


3. The called routine must do a RETURN a (n is two times the number of 
parameters in the argument list) to adjust the stack to the start of the 
calling sequence. Also, programs must be defined by a PROC FAR 
statement. 


4. Values are returned to cw-nasic by including in the argument list the 
variable name that receives the result. 


5. If the argument is a string, the parameter offset points to three bytes 
called the string descriptor. Byte 0 of the string descriptor contains the 
length of the string (0 to 255). Bytes 1 and 2, respectively, are the lower 
and upper eight bits of the string starting address in string space. 


Note The called routine must not change the contents of any of the three 
bytes of the string descriptor. 


6. Strings may be altered by user routines, but their length must not be 
changed. cw-BAsic cannot correctly manipulate strings if their lengths are 
modified by external routines. 


7. If the argument is a string literal in the program, the string descriptor 
points to program text. Be careful not to alter or destroy your program 
this way. To avoid unpredictable results, add +"" to the string literal in the 
program. For example, the following line forces the string literal to be 
copied into string space allocated outside of program memory space: 


20 AS="BASIC"+"" 
The string can then be modified without affecting the program. 
Examples: 


100 DEF SEG=&H2000 
110 ACC=&H7FA 
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120 CALL ACC (A,B$,C) 


Line 100 sets the segment to 2000 hex. The value of variable ACC is added 
into the address as the low word after the DEF SEG value is left-shifted four 
bits (this is a function of the microprocessor, not of cw-Basic). Here, ACC is set 
to &H7FA, so that the call to ACC executes the subroutine at location 
2000:7FA hex. 


Upon entry, only 16 bytes (eight words) remain available within the allocated 
stack space. If the called program requires additional stack space, then the user 
program must reset the stack pointer to a new allocated space. Be sure to 
restore the stack pointer adjusted to the start of the calling sequence on return to 
GW-BASIC. 

The following assembly language sequence demonstrates access of the 
parameters passed and storage of a return result in the variable C. 


Note The called program must know the variable type for numeric parameters 
passed. In these examples, the following instruction copies only two bytes: 


MOVSW 


This is adequate if variables A and C are integer. It would be necessary to copy 
four bytes if they were single precision, or copy eight bytes if they were double 
precision. 


MOV BP, SP Gets the current stack position 
in BP 

MOV BX, 8[BP] Gets the address of B$ 
description 

MOV CL, [BX] Gets the length of BS in CL 

MOV DX,1(BX] Gets the address of BS string 
descriptor in DX 

MOV SI,10[BP] Gets the address of A in SI 

MOV DI, 6[BP] Gets the pointer to C in DI 

MOVSW Stores variable A in ’C’ 


RET 6 Restores stack; returns 
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D.3 USR Function Calls 


Although the CALL statement is the recommended way of calling assembly 
language subroutines, the USR function call is still available for compatibility 
with previously-written programs. 


Syntax: 


USR[n](argument) 
nis anumber from 0 to 9 which specifies the USR routine being called (see 
DEF USR statement). If n is omitted, USRO is assumed. 


argument is any numeric or string expression. 


In cw-Basic a DEF SEG statement should be executed prior to a USR function 
call to ensure that the code segment points to the subroutine being called. The 
segment address given in the DEF SEG statement determines the starting 
segment of the subroutine. 

For each USR function call, a corresponding DEF USR statement must have 
been executed to define the USR function call offset. This offset and the 
currently active DEF SEG address determine the starting address of the 
subroutine. 

When the USR function call is made, register AL contains the number type flag 
(NTF), which specifies the type of argument given. The NTF value may be one 
of the following: 


NTF Value Specifies 


2 a two-byte integer (two’s complement format) 
3 a string 

4 a single-precision floating-point number 

8 a double-precision floating-point number 


If the argument of a USR function call is a number (AL<>73), the value of the 
argument is placed in the floating-point accumulator (FAC). The FAC is 8 
bytes long and is in the cw-sasic data segment. Register BX will point at the 
fifth byte of the FAC. Figure D.3 shows the representation of all the Gw-Basic 
number types in the FAC: 
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least most 
significant | significant Integer 
byte byte 
least most exponent . 
significant significant} minus poingle 
byte byte 128 Fectsion 


sign 























byte 
l | 
/ east most exponent 
significant significant; minus Double 
byte byte 128 Precision 
sign 
byte 


Figure D.3 Number Types in the Floating-Point Accumulator 


If the argument is a single-precision floating-point number: 
e  BX+3 is the exponent, minus 128. The binary point is to the left of the 
most significant bit of the mantissa. 


e BX+2 contains the highest seven bits of mantissa with leading 1 
suppressed (implied). Bit 7 is the sign of the number (0=positive, 
1=negative). 

e BX+1 contains the middle 8 bits of the mantissa. 

e BX+0 contains the lowest 8 bits of the mantissa. 


If the argument is an integer: 

e BX-+1 contains the upper eight bits of the argument. 

e BX+0 contains the lower eight bits of the argument. 

If the argument is a double-precision floating-point number: 


e BX-+0 through BX+3 are the same as for single precision floating point. 


ə BX-1 to BX4 contain four more bytes of mantissa. BX-4 contains the 
lowest eight bits of the mantissa. 
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If the argument is a string (indicated by the value 3 stored in the AL register) 
the (DX) register pair points to three bytes called the string descriptor. Byte 0 
of the string descriptor contains the length of the string (0 to 255). Bytes 1 and 
2, respectively, are the lower- and upper-eight bits of the string starting address 
in the Gw-Basic data segment. 


If the argument is a string literal in the program, the string descriptor points to 
program text. Be careful not to alter or destroy programs this way (see the 
preceding CALL statement). 


Usually, the value returned by a USR function call is the same type (integer, 
string, single precision, or double precision) as the argument that was passed to 
it. The registers that must be preserved are the same as in the CALL statement. 


A far retum is required to exit the USR subroutine. The returned value must be 
stored in the FAC. 


D.4 Programs That Call 
Assembly Language Programs 


This section contains two sample Gw-Basic programs that 


e load an assembly language routine to add two numbers together 

e return the sum into memory 

e remain resident in memory 

The code segment and offset to the first routine is stored in interrupt vector at 
0:100H. 


Example 1 calls an assembly language subroutine: 


Example 1 


10 DEF SEG=0 

100 CS=PEEK (&H102) +PEEK (&H103) *256 

200 OFFSET=PEEK (&H100) +PEEK (&H101) *256 
250 DEF SEG 
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300 C1%=2 :C2%=3:C3%=0 

400 TWOSUM=OF FSET 

500 DEF SEG=CS 

600 CALL TWOSUM (C1%,C2%,C3%) 
700 PRINT C3% 

800 END 


The assembly language subroutine called in the above program must be 
assembled, linked, and converted to a .COM file. The program, when executed 
prior to the running of the Gw-Basic program, will remain in memory until the 
system power is turned off, or the system is rebooted. 


0100 org 100H 
0100 double segment 
assume cs:double 

0100 EB 17 90 start: jmp startl 

0103 usrprg proc far 

0103 55 push bp 

0104 8B EC mov bp,sp 

0106 8B 76 08 mov si, [bp]+8 ;get address of 
;Pparameter b 

0109 8B 04 mov ax, [si] 7;get value of b 

010B 8B 76 OA mov si, [bp] +10 ;get address of 
;Pparameter a 

010E 03 04 add ax, [si] ;add value of 
za to value of 
jb 

0110 8B 7E 06 mov di, [bp]+6 ;get address of 
;Pparameter c 

0113 89 05 mov di,ax ;store sum in 
;parameter c 

0115 5D pop bp 

0116 ca 0006 ret 6 

0119 usrprg endp 
¿Program to put 
;procedure in 
memory 
zand remain 
resident 
;The offset and 
; segment are 
stored 
jin location 
;100-103H. 

0119 Startl: 

0119 B8 0000 mov ax,0 


011c 8E D8 mov ds,ax ;data segment 


011E 
0100 


0121 
0125 


0127 
012A 


012C 
012F 
0131 
0133 
0136 
0137 
0138 
013B 
013D 
013D 
013F 
O13F 
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sto 0000H 


BB 0100 mov bx, 
H ;pointer to int 
¿vector 100H 
83 7F 02 0 cmp word ptr [bx],0 
75 16 jne quit j; program 
jalready run, 
pexit 
83 3F 00 cmp word ptr2 [bx],0 
75 11 jne quit ; program 
;already run, 
rexit 
B8 0103 R mov ax,offset usrprg 
89 07 mov [bx],ax ;program offset 
8C c8 mov ax,cs 
89 47 02 mov [bx+2],ax j;data segment 
OE push cs 
1F pop ds 
BA 0141 R mov dx,offset veryend 
CD 27 int 27h 
quit: 
CD 20 int 20h 
veryend: 
double ends 


end start 


Example 2 places the assembly language subroutine in the specified area: 


Example 2 


10 I=0:JC=0 
DIM A% (23) 
MEM%=VARPTR (A$ (1) ) 
FOR I=1 TO 23 
READ JC 

POKE MEM%, JC 
MEM%=MEM%+1 


100 
150 
200 
300 
400 
450 
500 
600 
700 
800 
900 
950 
1000 
1100 
1200 


NEXT 


C1%=2:C2%=3:C3%=0 
TWOSUM=VARPTR (Ab (1) ) 
CALL TWOSUM(C1%,C2%,C3%) 
PRINT C3% 


END 


DATA &H55, &H8b, &Hec &H8b, &H76, &H08, &H8b, &H04, &H8b, &H76 
DATA &H0a, &HO3, &H04, &H8b, &H7e, &H06, &H89, &HOS, &HSd 
DATA &Hca, &H06, &HOO 


Appendix E 
Converting BASIC 
Programs to GW-BASIC 


Programs written in a Basic language other than Gw-Basic may require some 
minor adjustments before they can be run. The following sections describe 
these adjustments. 


E.1 String Dimensions 


Delete all statements used to declare the length of strings. A statement such as 
the following: 

DIM AS$(I,J) 

which dimensions a string array for J elements of length I, should be converted 
to the following statement: 

DIM A$ (J) 


Some cw-sasic languages use a comma or ampersand (&) for string 
concatenation. Each of these must be changed to a plus sign (+), which is the 
operator for GW-BASIC string concatenation. 

In cw-sasic, the MID$, RIGHT$, and LEFT$ functions are used to take 
substrings of strings. Forms such as A$(1) to access the Ith character in A$, or 
A$(I,J) to take a substring of A$ from position I to position J, must be changed 
as follows: 


Other BASIC: GW-BASIC: 


X$=A$(1) X$=MID$(A$,I,1) 
X$=A$(,J) X$=MID$(A$,I,J-I+1) 
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If the substring reference is on the left side of an assignment, and X$ is used to 
replace characters in A$, convert as follows: 


Other BASIC: GW-BASIC: 
AS()=X$ MIDS(AS$,I,1)=X$ 
AS(LJ)=X$ MIDS(AS,1,J-I+1)=X$ 


E.2 Multiple Assignments 


Some cw-sasic languages allow statements of the following form to set B and C 
equal to zero: 


10 LET B=C=0 


GW-BASIC would interpret the second equal sign as a logical operator and set B 
equal to -1 if C equaled 0. Convert this statement to two assignment statements: 


10 Cc=0:B=0 
E.3 Multiple Statements 


Some cw-sasic languages use a backslash (\) to separate multiple statements on 
a line. With Gw-sasic, be sure all elements on a line are separated by a colon (:). 


E.4 MAT Functions 


Programs using the MAT functions available in some cw-asic languages must 
be rewritten using FOR-NEXT loops to execute properly. 
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E.5 FOR-NEXT Loops 


Some cGw-Basic languages will always execute a FOR-NEXT loop once, 
regardless of the limits. Gw-Basic checks the limits first and does not execute the 


loop if past limits. 











Appendix F 
Communications 


This appendix describes the Gw-Basic statements necessary to support RS-232 
asynchronous communications with other computers and peripheral devices. 


F.1 Opening Communications Files 


The OPEN COM statement allocates a buffer for input and output in the same 
manner as the OPEN statement opens disk files. 


F.2 Communications I/O 


Since the communications port is opened as a file, all I/O statements valid for 
disk files are valid for COM. 


COM sequential input statements are the same as those for disk files: 


INPUT# 
LINE INPUT# 
INPUTS 


COM sequential output statements are the same as those for diskette: 


PRINT # 
PRINT# USING 


See the GW-BASIC User's Reference for more information on these statements. 
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F.3 The COM I/O Functions 


The most difficult aspect of asynchronous communications is processing 
characters as quickly as they are received. At rates above 2400 baud (bps), it is 
necessary to suspend character transmission from the host long enough for the 
receiver to catch up. This can be done by sending XOFF (crrt-s) to the host to 
temporarily suspend transmission, and XON (cTRL-Q) to resume, if the 
application supports it. 


GW-BASIC provides three functions which help to determine when an overrun 
condition is imminent: 


LOC(x) Returns the number of characters in the input queue waiting to 
be read. The input queue can hold more than 255 characters 
(determined by the /c: switch). If there are more than 255 
characters in the queue, LOC(x) returns 255. Since a string is 
limited to 255 characters, this practical limit alleviates the need 
for the programmer to test for string size before reading data 
into it. 

LOF(x) Returns the amount of free space in the input queue; that is 
/c:(size)-number of characters in the input queue 


LOF may be used to detect when the input queue is reaching 
storage capacity. 

EOF(x) True (-1), indicates that the input queue is empty. False (0) is 
retumed if any characters are waiting to be read. 


F.4 Possible Errors: 


A "Communications buffer overflow” error occurs if a read is attempted after 
the input queue is full (that is, LOC(x) returns 0). 


A "Device I/O" error occurs if any of the following line conditions are detected 
on receive: overrun error (OE), framing error (FE), or break interrupt (BI). The 
error is reset by subsequent inputs, but the character causing the error is lost. 
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A "Device fault” error occurs if data set ready (DSR) is lost during I/O. 


A "Parity error" occurs if the PE (parity enable) option was used in the OPEN 
COM statement and incorrect parity was received. 


F.5 The INPUTS Function 


The INPUT$ function is preferred over the INPUT and LINE INPUT 
statements for reading COM files, because all ASCII characters may be 
significant in communications. INPUT is least desirable because input stops 
when a comma or an enter is seen. LINE INPUT terminates when an enter is 
seen. 


INPUTS allows all characters read to be assigned to a string. 


INPUTS returns x characters from the y file. The following statements then are 
most efficient for reading a COM file: 


10 WHILE NOT EOF (1) 

20 AS=INPUTS (LOC (1) , #1) 

IO haw 

40 ... Process data returned in A$ 

50) Ls. 

60 WEND 

This sequence of statements translates: As long as something is in the input 
queue, return the number of characters in the queue and store them in A$. If 
there are more than 255 characters, only 255 are returned at a time to prevent 
string overflow. If this is the case, EOF(1) is false, and input continues until the 
input queue is empty. 
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GET and PUT Statements for COM Files 


Purpose: 


To allow fixed-length I/O for COM. 
Syntax: 


GET filenumber, nbytes PUT filenumber, nbytes 


Comments: 


filenumber is an integer expression returning a valid file number. 


nbytes is an integer expression returning the number of bytes to be transferred 
into or out of the file buffer. nbytes cannot exceed the value set by the /s: 
switch when Gw-sasic was invoked. 


Because of the low performance associated with telephone line 
communications, it is recommended that GET and PUT not be used in such 
applications. 


Example: 


The following TTY sample program is an exercise in communications I/O. It is 
designed to enable your computer to be used as a conventional terminal. 
Besides full-duplex communications with a host, the TTY program allows data 
to be downloaded to a file. Conversely, a file may be uploaded (transmitted) to 
another machine. 


In addition to demonstrating the elements of asynchronous communications, 
this program is useful for transferring Gw-Basic programs and data to and from a 
computer. 


Note This program is set up to communicate with a DEC® SYSTEM-20 
especially in the use of XON and XOFF. It may require modification to 
communicate with other types of hardware. 
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F.6 The TTY Sample Program 


10 SCREEN 0,0:WIDTH 80 

15 KEY OFF:CLS: CLOSE 

20 DEFINT A-Z 

25 LOCATE 25,1 

30 PRINT STRINGS (60," ") 

40 FALSE=0:TRUE=NOT FALSE 

50 MENU=5 ‘Value of MENU Key (^E) 

60 XOFFS=CHRS (19) :XONS=CHR$ (17) 

100 LOCATE 25,1:PRINT "Async TTY Program"; 

110 LOCATE 1,1:LINE INPUT "Speed?"; "SPEEDS 

120 COMFILS="COM1:,+SPEEDS+",E,7" 

130 OPEN COMFILS AS #1 

140 OPEN "SCRN: "FOR OUTPUT AS #3 

200 PAUSE=FALSE 

210 AS=INKEYS:IF AS=""THEN 230 

220 IF ASC(AS)=MENU THEN 300 ELSE PRINT #1,AS; 
230 IF EOF(1) THEN 210 

240 IF LOC(1)>128 THEN PAUSE=TRUE:PRINT #1, XOFFS; 
250 AS=INPUTS (LOC (1), #1) 

260 PRINT #3,A$;:IF LOC(1)>0 THEN 240 

270 IF PAUSE THEN PAUSE=FALSE:PRINT #1, XONS; 
280 GOTO 210 

300 LOCATE 1,1:PRINT STRINGS (30,32) : LOCATE 1,1 
310 LINE INPUT "FILE?";DSKFIL$ 

400 LOCATE 1,1:PRINT STRINGS (30,32) :LOCATE 1,1 
410 LINE INPUT" (T)ransmit or (R)eceive?"; TXRX$ 
420 IF TXRXS="T" THEN OPEN DSKFILS FOR INPUT AS 
#2;GOTO 1000 

430 OPEN DSKFILS FOR OUTPUT AS #2 

440 PRINT #1,CHRS (13); 

500 IF EOF(1) THEN GOSUB 600 

510 IF LOC(1)>128 THEN PAUSE=TRUE:PRINT #1, XOFFS; 
520 AS=INPUTS (LOC (1), #1) 

530 PRINT #2,A$;:IF LOC(1)>0 THEN 510 

540 IF PAUSE THEN PAUSE=FALSE:PRINT #1, XONS; 
550 GOTO 500 

600 FOR I=1 TO 5000 

610 IF NOT EOF (1) THEN I=9999 

620 NEXT I 

630 IF I>9999 THEN RETURN 

640 CLOSE #2;CLS: LOCATE 25,10:PRINT "* Download 
complete *"; 
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650 RETURN 200 

1000 WHILE NOT EOF (2) 

1010 AS=INPUTS (1, #2) 

1020 PRINT #1,AS; 

1030 WEND 

1040 PRINT #1,CHRS$(28);*%Z to make close file. 


1050 CLOSE #2:CLS:LOCATE 25,10:PRINT "** Upload 
complete **"; 

1060 GOTO 200 

9999 CLOSE: KEY ON 


F.7 Notes on the TTY Sample Program 


Note Asynchronous implies character I/O as opposed to line or block I/O. 
Therefore, all prints (either to the COM file or screen) are terminated with a 
semicolon (;). This retards the return line feed normally issued at the end of the 
PRINT statement. 


Line Number Comments 

10 Sets the SCREEN to black and white alpha mode and sets 
the width to 80. 

15 Tums off the soft key display, clears the screen, and makes 


sure that all files are closed. 


20 Defines all numeric variables as integer, primarily for the 
benefit of the subroutine at 600-620. Any program looking 
for speed optimization should use integer counters in loops 
where possible. 


40 Defines boolean true and false. 

50 Defines the ascu (ASC) value of the MENU key. 

60 Defines the ascn XON and XOFF characters. 

100-130 Prints program ID and asks for baud rate (speed). Opens 
communications to file number 1, even parity, 7 data bits. 

200-280 This section performs full-duplex I/O between the video 


screen and the device connected to the RS-232 connector 
as follows: 


300-320 


400-420 


430 


8. 
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Read a character from the keyboard into A$. INKEY$ 
returns a null string if no character is waiting. 


If a keyboard character is available, waiting, then: 


If the character is the MENU key, the operator is 
ready to down-load a file. Get filename. 

If the character (A$) is not the MENU key send it by 
writing to the communications file (PRINT #1...). 


If no character is waiting, check to see if any 
characters are being received. 


At 230, see if any characters are waiting in COM 
buffer. If not, go back and check the keyboard. 


At 240, if more than 128 characters are waiting, set 
PAUSE flag to indicate that input is being suspended. 
Send XOFF to host, stopping further transmission. 


At 250-260, read and display contents of COM buffer 
on screen until empty. Continue to monitor size of 
COM buffer (in 240). Suspend transmission if 
reception falls behind. 


Resume host transmission by sending XON only if 
suspended by previous XOFF. 


Repeat process until the MENU key is pressed. 


Get disk filename to be down-loaded to. Open the file as 
number 2. 


Asks if file named is to be transmitted (uploaded) or 
received (down-loaded). 


Receive routine. Sends a RETURN to the host to begin the 
down-load. This program assumes that the last command 
sent to the host was to begin such a transfer and was 
missing only the terminating return. If a DEC system is the 
host, such a command might be 
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500 


510 


520-530 


540-550 


600-650 


1000-1060 


9999 


COPY TTY:=MANUAL.MEM (MENU Key) 
if the MENU key was struck instead of RETURN. 


When no more characters are being received, (LOC(x) 
returns 0), then performs a timeout routine. 


If more than 128 characters are waiting, signal a pause and 
send XOFF to the host. 


Read all characters in COM queue (LOC(x)) and write 
them to diskette (PRINT #2...) until reception is caught up 
to transmission. 


If a pause is issued, restart host by sending XON and 
clearing the pause flag. Continue the process until no 
characters are received for a predetermined time. 


Time-out subroutine. The FOR loop count was determined 
by experimentation. If no character is received from the 
host for 17-20 seconds, transmission is assumed complete. 
If any character is received during this time (line 610), then 
set n well above the FOR loop range to exit loop and 
return to caller. If host transmission is complete, close the 
disk file and resume regular activities. 


Transmit routine. Until end of disk file, read one character 
into A$ with INPUTS statement. Send character to COM 
device in 1020. Send a ^Z at end of file in 1040 in case 
receiving device needs one to close its file. Lines 1050 and 
1060 close disk file, print completion message, and go 
back to conversation mode in line 200. 


Presently not executed. As an exercise, add some lines to 
the routine 400-420 to exit the program via line 9999. This 
line closes the COM file left open and restores the function 
key display. 


Appendix G 
Hexadecimal Equivalents 


Table G.1 lists decimal and binary equivalents to hexadecimal values. 


Table G.1 
Decimal and Binary Equivalents to Hexadecimal Values 


Hexadecimal Equals Equals 


Value Decimal: Binary: 


0000 
0001 
0010 
0011 
0100 
0101 
0110 
0111 
1000 
1001 
1010 
1011 
1100 
1101 
1110 
1111 


MMOAWPOCMIDNAWNHHO 
COIRNERWNHO 


— oe č j j 
A kWNF © 
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Table G.2 lists decimal equivalents to hexadecimal values. 


Table G.2 
Decimal Equivalents to Hexadecimal Values 


Hexadecimal Equals Hexadecimal Equals 

Value Decimal: Value: Decimal: 

0 0 80 128 

1 1 

2 2 

3 3 ; 

4 4 90 144 

5 5 

6 6 

7 7 ; 

8 8 AO 160 

9 9 

A 10 

B 11 : 

C 12 BO 176 

D 13 

E 14 

F 15 ; 

10 16 CO 192 

11 17 

12 18 

13 19 ‘ 

14 20 DO 208 

15 21 

16 22 

17 23 . 

18 24 EO 224 

19 25 

1A 26 

1B 27 ; 

1C 28 FO 240 

1D 29 100 256 

1E 30 200 512 

1F 31 300 768 

20 32 400 1024 
500 1280 
600 1536 


700 1792 
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Table G.2 (continued) 


Hexadecimal Equals Hexadecimal Equals 

Value Decimal: Value: Decimal: 

30 48 800 2048 
900 2304 
A00 2560 

; ‘ BOO 2816 

40 64 coo 3072 

: : D00 3328 
E00 3584 

. 3 F00 3840 

50 80 1000 4096 

; : 2000 8192 
3000 12288 

i ; 4000 16384 

60 96 5000 20480 

i 6000 24576 
7000 28672 

; : 8000 32768 

70 112 9000 36864 

; ; A000 40960 
B000 45056 
C000 49152 
D000 53248 
E000 57344 


F000 61440 


Appendix H 
Key Scan Codes 


Keytop Legend Scancode 
ESC 01 
1/! 02 
2/@ 03 
3/# 04 
05 
5/% 06 
6/4 07 
7/& 08 
8/* 09 
9/( 0A 
0/) OB 
-/_ 0C 
=/+ oD 
BACKSPACE OE 
TAB OF 
Q 10 
WwW 11 
E 12 
R 13 
T 14 
Y 15 
U 16 
I 17 
O 18 
P 19 
[/{ 1A 
V3 1B 
ENTER 1C 
CTRL 1D 
A 1E 
S 1F 
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Keytop Legend Scancode 
F 21 
G 22 
H 23 
J 24 
K 25 
L 26 
;/: 27 
”/" 28 
’/~ 29 
Left sHIFT 2A 
I 2B 
Z 2C 
X 2D 
C 2E 
V 2F 
B 30 
N 31 
M 32 
is 33 
In 35 
Right sHFT 36 
* /PRTSC 37 
ALT 38 
SPACEBAR 39 
CAPS LOCK 3A 
F1 3B 
F2 3C 
F3 3D 
F4 3E 
F5 3F 
F6 40 
F7 41 
F8 42 
F9 43 
F10 44 
NUM LOCK 45 
SCROLL LOCK 46 
7/HOME 47 
8/CURSOR UP 48 


9 /PGUP 49 


Keytop Legend 


4/CURSOR LEFT 
5 

6/CURSOR RIGHT 
+ 

1/END 
2/CURSOR DOWN 
3/PGDN 

O/iIns 

[DEL 
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Scancode 


4A 
4B 
4C 
4D 
4E 
4F 
50 

51 

52 
53 


Appendix | 
Characters Recognized 
by GW-BASIC 


The Gw-sasic character set includes all characters that are legal in Gw-Basic 
commands, statements, functions, and variables. The set comprises alphabetic, 
numeric, and special characters. 


The alphabetic characters in Gw-sasic are the uppercase and lowercase letters of 


the alphabet. 


The numeric characters in Gw-sasic are the digits 0 through 9. 


The following special characters and terminal keys are recognized by Gw-BASIC: 


Character 


Description 


Blank. 

Equal sign or assignment symbol. 

Plus sign or string concatenation. 

Minus sign. 

Asterisk or multiplication symbol. 

Slash or division symbol. 

Caret, exponentiation symbol, or cTRL key. 
Left parenthesis. 

Right parenthesis. 

Percent or integer declaration. 

Number sign or double-precision declaration. 
Dollar sign or string declaration. 
Exclamation point or single-precision declaration. 
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~ 


Qi A 


BACKSPACE 
ESC 
TAB 


CURSOR 
RETURN 


Left bracket. 

Right bracket. 

Comma. 

Double quotation marks or string delimiter. 

Period, dot, or decimal point. 

Single quotation mark, apostrophe, or remark indicator. 
Semicolon or carriage return suppressor. 

Colon or line statement delimiter. 


Ampersand or descriptor for hexadecimal and octal 
number conversion. 


Question mark. 

Less than symbol. 

Greater than symbol. 

Backslash or integer division symbol. 

"AL" sign. 

Underscore. 

Deletes last character typed. 

Erases the current logical line from the screen. 


Moves print position to next tab stop. Tab stops are every 
eight columns. 


Moves cursor to next physical line. 


Terminates input to a line and moves cursor to beginning of 
the next line, or executes statement in direct mode. 


Glossary 


abend 

An acronym for abnormal end of task. An abend is the termination of computer 
processing on a job or task prior to its completion because of an error 

condition that cannot be resolved by programmed recovery procedures. 
access 


The process of seeking, reading, or writing data on a storage unit. 


access methods 

Techniques and programs used to move data between main memory and 
input/output devices. 

accuracy 

The degree of freedom from error. Accuracy is often confused with precision, 
which refers to the degree of preciseness of a measurement. 

acronym 

A word formed by the initial letters of words or by initial letters plus parts of 
several words. Acronyms are widely used in computer technology. For 
example, COBOL is an acronym for COmmon Business Oriented Language. 
active partition 

A section of the computer’s memory that houses the operating system being 
used. 

address 

A name, label, or number identifying a register, location or unit where 
information is stored. 

algebraic language 


A language whose statements are structured to resemble the structure of 
algebraic expression. Fortran is a good example of an algebraic language. 
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algorithm 


A set of well-defined rules or procedures to be followed in order to obtain the 
solution of a problem in a finite number of steps. An algorithm can involve 
arithmetic, algebraic, logical and other types of procedures and instructions. 
An algorithm can be simple or complex. However, all algorithms must produce 
a solution within a finite number of steps. Algorithms are fundamental when 
using a computer to solve problems, because the computer must be supplied 
with a specific set of instructions that yields a solution in a reasonable length 
of time. 


alphabetic 


Data representation by alphabetical characters in contrast to numerical; the 
letters of the alphabet. 


alphanumeric 


A contraction of the words alphabetic and numeric; a set of characters 
including letters, numerals, and special symbols. 


application 


The system or problem to which a computer is applied. Reference is often 
made to an application as being either of the computational type, in which 
arithmetic computations predominate, or of the data processing type, in which 
data handling operations predominate. 


application program 


A computer program designed to meet specific user needs. 


argument 


1. A type of variable whose value is not a direct function of another 
variable. It can represent the location of a number in a mathematical 
operation, or the number with which a function works to produce its 
results. 


2. A known reference factor that is required to find a desired item (function) 
in a table. For example, in the square root function SQRT(X), X is the 
argument. The value of X determines the square root value returned by 
this function. 
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array 

1. An organized collection of data in which the argument is positioned 
before the function. 

2. A group of items or elements in which the position of each item or 
element is significant. A multiplication table is a good example of an 
array. 


ASCII 


Acronym for American Standard Code for Information Interchange. ascu is a 
standardized 8-bit code used by most computers for interfacing. 


asci was developed by the American National Standards Institute (ans). It 
uses 7 binary bits for information and the 8th bit for parity purposes. 


assembler 


A computer program that produces a machine-language program which may 
then be directly executed by the computer. 


assembly language 


A symbolic language that is machine-oriented rather than problem-oriented. A 
program in an assembly language is converted by an assembler to a machine- 
language program. Symbols representing storage locations are converted to 
numerical storage locations; symbolic operation codes are converted to numeric 
operation codes. 


asynchronous 
1. Not having a regular time or clocked relationship. See synchronous. 


2. A type of computer operation in which a new instruction is initiated when 
the former instruction is completed. Thus, there is no regular time 
schedule, or clock, with respect to instruction sequence. The current 
instruction must be complete before the next is begun, regardless of the 
length of time the current instruction takes. 


asynchronous communication 


A way of transmitting data serially from one device to another, in which each 
transmitted character is preceded by a start bit and followed by a stop bit. This 
is also called start/stop transmission. 


back-up 


1. A second copy of data on a diskette or other medium, ensuring recovery 
from loss or destruction of the original media. 
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2. On-site or remote equipment available to complete an operation in the 
event of primary equipment failure. 

BASIC 

Acronym for Beginner’s All-purpose Symbolic Instruction Code. Basic is a 

computer programming language developed at Dartmouth College as an 

instructional tool in teaching fundamental programming concepts. This 

language has since gained wide acceptance as a time-sharing language and is 

considered one of the easiest programming languages to learn. 


batch processing 


A method of operating a computer so that a single program or set of related 
programs must be completed before the next type of program is begun. 


baud 


A unit of measurement of data processing speed. The speed in bauds is the 
number of signal elements per second. Since a signal element can represent 
more than one bit, baud is not synonymous with bits-per-second. Typical baud 
rates are 110, 300, 1200, 2400, 4800, and 9600. 


binary 
1. A characteristic or property involving a choice or condition in which there 
are two possibilities. 


2. Anumbering system which uses 2 as its base instead of 10 as in the 
decimal system. The binary system uses only two digits, 0 and 1, in its 
written form. 


3. A device whose design uses only two possible states or levels to perform 
its functions. A computer executes programs in binary form. 


binary digit 

A quantity which is expressed in the binary digits of 0 and 1. 

bit 

A contraction of "binary digit". A bit can either be 0 or 1, and is the smallest 
unit of information recognizable by a computer. 
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block 


An amount of storage space or data, of arbitrary length, usually contiguous, 
and often composed of several similar records, all of which are handled as a 
unit. 


boolean logic 


A field of mathematical analysis in which comparisons are made. A 
programmed instruction can cause a comparison of two fields of data, and 
modify one of those fields or another field as a result of comparison. This 
system was formulated by British mathematician George Boole (1815-1864). 
Some boolean operators are OR, AND, NOT, XOR, EQV, and IMP. 


boot 


A machine procedure that allows a system to begin operations at the desired 
level by means of its own initiation. The first few instructions are loaded into a 
computer from an input device. These instructions allow the rest of the system 
to be loaded. The word boot is abbreviated from the word bootstrap. 


bps 


Bits per second. 


buffer 


A temporary storage area from which data is transferred to or from various 
devices. 


built-in clock 


A real-time clock that lets your programs use the time of day and date. Built 
into MS-DOS, it lets you set the timing of a program. It can be used to keep a 
personal calendar, and it automatically measures elapsed time. 


byte 


An element of data which is composed of eight data bits plus a parity bit, and 
represents either one alphabetic or special character, two decimal digits, or 
eight binary bits. Byte is also used to refer to a sequence of eight binary digits 
handled as a unit. It is usually encoded in the ascu format. 


calculation 


A series of numbers and mathematical signs that, when entered into a 
computer, is executed according to a series of instructions. 
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central processor (CPU) 


The heart of the computer system, where data is manipulated and calculations 
are performed. The CPU contains a control unit to interpret and execute the 
program and an arithmetic-logic unit to perform computations and logical 
processes. It also routes information, controls input and output, and 
temporarily stores data. 


chaining 
The use of a pointer in a record to indicate the address of another record 
logically related to the first. 


character 


Any single letter of the alphabet, numeral, punctuation mark, or other symbol 
that a computer can read, write, and store. Character is synonymous with the 
term byte. 


COBOL 


Acronym for COmmon Business-Oriented Language, a computer language 
suitable for writing complicated business applications programs. It was 
developed by copasyL, a committee representing the U. S. Department of 
Defense, certain computer manufacturers, and major users of data processing 
equipment. coBoL is designed to express data manipulations and processing 
problems in English narrative form, in a precise and standard manner. 


code 

1. To write instructions for a computer system 
2. To classify data according to arbitrary tables 
3. To use a machine language 
4. 


To program 


command 


A pulse, signal, word, or series of letters that tells a computer to start, stop, or 
continue an operation in an instruction. Command is often used incorrectly as a 
synonym for instruction. 


compatible 


A description of data, programs or equipment that can be used between 
different kinds of computers or equipment. 
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compiler 

A computer program that translates a program written in a problem-oriented 
language into a program of instructions similar to, or in, the language of the 
computer. 

computer network 

A geographically dispersed configuration of computer equipment connected by 
communication lines and capable of load sharing, distributive processing, and 
automatic communication between the computers within the network. 
concatenate 

To join together data sets, such as files, in a series to form one data set, such as 
one new file. The term concatenate literally means "to link together.” A 
concatenated data set is a collection of logically connected data sets. 
configuration 

In hardware, a group of interrelated devices that constitute a system. In 
software, the total of the software modules and their interrelationships. 
constant 


A never-changing value or data item. 


coprocessor 

A microprocessor device connected to a central microprocessor that performs 
specialized computations (such as floating-point arithmetic) much more 
efficiently than the CPU alone. 

cursor 

A blinking line or box on a computer screen that indicates the next location for 
data entry. 

data 

A general term used to signify all the basic information elements that can be 
produced or processed by a computer. See information. 

data element 

The smallest named physical data unit. 


8 GW-BASIC User's Guide 


data file 

A collection of related data records organized in a specific manner. Data files 
contain computer records which contain information, as opposed to containing 
data handling information or a program. 

debug 

The process of checking the logic of a computer program to isolate and remove 
mistakes from the program or other software. 

default 

An action or value that the computer automatically assumes, unless a different 
instruction or value is given. 

delimit 


To establish parameters; to set a minimum and a maximum. 


delimiter 

A character that marks the beginning or end of a unit of data on a storage 
medium. Commas, semi-colons, periods, and spaces are used as delimiters to 
separate and organize items of data. 

detail file 


A data file composed of records having similar characteristics, but containing 
data which is relatively changeable by nature, such as employee weekly 
payroll data. Compare to master file. 

device 

A piece of hardware that can perform a specific function. A printer is an 
example of a device. 

diagnostic programs 


Special programs used to align equipment or isolate equipment malfunctions. 


directory 

A table that gives the name, location, size, and the creation or last revision date 
for each file on the storage media. 

diskette 


A flat, flexible platter coated with magnetic material, enclosed in a protective 
envelope, and used for storage of software and data. 
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Disk Operating System 

A collection of procedures and techniques that enable the computer to operate 
using a disk drive system for data entry and storage. Disk Operating System is 
usually abbreviated to DOS. 

DOS 


The acronym for Disk Operating System. pos rhymes with "boss." 


double-density 

A type of diskette that has twice the storage capacity of standard single-density 
diskettes. 

double-precision 


The use of two computer words to represent each number. This technique 
allows the use of twice as many digits as are normally available and is used 
when extra precision is needed in calculations. 


double-sided 

A term that refers to a diskette that can contain data on both surfaces of the 
diskette. 

drive 

A device that holds and manipulates magnetic media so that the CPU can read 
data from or write data to them. 

end-of-file mark (EOF) 

A symbol or machine equivalent that indicates that the last record of a file has 
been read. 

erase 


To remove or replace magnetized spots from a storage medium. 


error message 

An audible or visual indication of hardware or software malfunction or of an 
illegal data-entry attempt. 

execute 


To carry out an instruction or perform a routine. 
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exponent 


A symbol written above a factor and on the right, telling how many times the 
factor is repeated. In the example of A2, A is the factor and 2 is the exponent. 
A2 means A times A (A x A). 


extension 


A one-to-three-character set that follows a filename. The extension further 
defines or clarifies the filename. It is separated from the filename by a 


period(.). 
field 
An area of a record that is allocated for a specific category of data. 


file 
A collection of related data or programs that is treated as a unit by the 
computer. 


file protection 
The devices or procedures that prevent unintentional erasure of data on a 
storage device, such as a diskette. 


file structure 

A conceptual representation of how data values, records, and files are related 
to each other. The structure usually implies how the data is stored and how the 
data must be processed. 

filename 

The unique name, usually assigned by a user, which is used to identify one file 
for all subsequent operations that use that file. 

fixed disk 


A hard disk enclosed in a permanently-sealed housing that protects it from 
environmental interference. Used for storage of data. 


floating-point arithmetic 


A method of calculation in which the computer or program automatically 
records, and accounts for, the location of the radix point. The programmer 
need not consider the radix location. 
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floating-point routine 

A set of program instructions that permits a floating-point mathematics 
operation in a computer which lacks the feature of automatically accounting for 
the radix point. 

format 

A predetermined arrangement of data that structures the storage of information 
on an external storage device. 

function 

A computer action, as defined by a specific instruction. Some Gw-BASIC 
functions are COS, EOF, INSTR, LEFT$, and TAN. 

function keys 

Specific keys on the keyboard that, when pressed, instruct the computer to 
perform a particular operation. The function of the keys is determined by the 
applications program being used. 

GIGO 


An informal term that indicates sloppy data processing; an acronym for 
Garbage In Garbage Out. The term cico is normally used to make the point 
that if the input data is bad (garbage in) then the output data will also be bad 
(garbage out). 

global search 

Used in reference to a variable (character or command), a global search causes 
the computer to locate all occurrences of that variable. 

graphics 

A hardware/software capability to display objects in pictures, rather than 
words, usually on a graphic (CRT) display terminal with line-drawing 
capability and permitting interaction, such as the use of a light pen. 

hard copy 

A printed copy of computer output in a readable form, such as reports, checks, 
or plotted graphs. 

hardware 


The physical equipment that compnises a system. 
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hexadecimal 


A number system with a base, or radix, of 16. The symbols used in this system 
are the decimal digits 0 through 9 and six additional digits which are generally 
represented as A, B, C, D, E, and F. 


hidden files 


Files that cannot be seen during normal directory searches. 


hierarchical directories 


See tree-structured directories. 


housekeeping functions 


Routine operations that must be performed before the actual processing begins 
or after it is complete. 


information 


Facts and knowledge derived from data. The computer operates on and 
generates data. The meaning derived from the data is information. That is, 
information results from data; the two words are not synonymous, although 
they are often used interchangeably. 


interpreter 


A program that reads, translates and executes a user’s program, such as one 
written in the Basic language, one line at a time. A compiler, on the other hand, 
reads and translates the entire user’s program before executing it. 


input 
1. The process or device concerning the entry of data into a computer. 


2. Actual data being entered into a computer. 


input/output 


A general term for devices that communicate with a computer. Input/output is 
usually abbreviated as I/O. 


instruction 


A program step that tells the computer what to do next. Instruction is often 
used incorrectly as a synonym for command. 
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integer 
A complete entity, having no fractional part. The whole or natural number. For 
example, 65 is an integer; 65.1 is not. 


integrated circuit 


A complete electronic circuit contained in a small semiconductor component. 


interface 


An information interchange path that allows parts of a computer, computers, 
and external equipment (such as printers, monitors, or modems), or two or 
more computers to communicate or interact. 


O 

The acronym for input/output. 

job 

A collection of tasks viewed by the computer as a unit. 

K 

The symbol signifying the quantity 210, which is equal to 1024. K is 
sometimes confused with the symbol k, (kilo) which is equal to 1000. 
logarithm 


A logarithm of a given number is the value of the exponent indicating the 
power required to raise a specified constant, known as the base, to produce that 
given number. That is, if B is the base, N is the given number and L is the 
logarithm, then BL = N. Since 103 = 1000, the logarithm to the base 10 of 
1000 is 3. 


loop 


A series of computer instructions that are executed repeatedly until a desired 
result is obtamed or a predetermined condition is met. The ability to loop and 
reuse instructions eliminates countless repetitious instructions and is one of the 
most important attributes of stored programs. 


M 


The symbol signifying the quantity 1,000,000 (106). When used to denote 
storage, it more precisely refers to 1,048,576 (220), 
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mantissa 


The fractional or decimal part of a logarithm of a number. For example, the 
logarithm of 163 is 2.212. The mantissa is 0.212, and the characteristic is 2.0. 


In floating-point numbers, the mantissa is the number part. For example, the 
number 24 can be written as 24,2 where 24 is the mantissa and 2 is the 
exponent. The floating-point number is read as .24 X 102, or 24. 


master file 

A data file composed of records having similar characteristics that rarely 
change. A good example of a master file would be an employee name and 
address file that also contains social security numbers and hiring dates. 
media 

The plural of medium. 


medium 

The physical material on which data is recorded and stored. Magnetic tape, 
punched cards, and diskettes are examples of media. 

memory 

The high-speed work area in the computer where data can be held, copied, and 
retrieved. 


menu 
A list of choices from which an operator can select a task or operation to be 


performed by the computer. 
microprocessor 


A semiconductor central processing unit (CPU) in a computer. 


modem 


Acronym for modulator demodulator. A modem converts data from a computer 
to analog signals that can be transmitted through telephone lines, or converts 
the signals from telephone lines into a form the computer can use. 


MS-DOS 
Acronym for Microsoft Disk Operating System. 
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nested programs or subroutines 


A program or subroutine that is incorporated into a larger routine to permit 
ready execution or access of each level of the routine. For example, nesting 
loops involves incorporating one loop of instructions into another loop. 


null 


Empty or having no members. This is in contrast to a blank or zero, which 
indicates the presence of no information. For example, in the number 540, zero 
contains needed information. 


numeric 
A reference to numerals as opposed to letters or other symbols. 
octal number system 


A representation of values or quantities with octal numbers. The octal number 
system uses eight digits: 0, 1, 2, 3, 4, 5, 6, and 7, with each position in an octal 
numeral representing a power of 8. The octal system is used in computing as a 
simple means of expressing binary quantities. 


operand 

A quantity or data item involved in an operation. An operand is usually 
designated by the address portion of an instruction, but it may also be a result, 
a parameter, or an indication of the name or location of the next instruction to 
be executed. 

operating system 

An organized group of computer instructions that manage the overall operation 
of the computer. 

operator 

A symbol indicating an operation and itself the subject of the operation. It 
indicates the process that is being performed. For example, + is addition, is 
subtraction, X is multiplication, and / is division. 

option 


An add-on device that expands a system’s capabilities. 


output 


Computer results, or data that has been processed. 
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parallel output 
The method by which all bits of a binary word are transmitted simultaneously. 


parameter 


A variable that is given a value for a specific program or run. A definable 
characteristic of an item, device, or system. 


parity 
An extra-bit of code that is used to detect data errors in memory by making the 
sum of the active bit in a data word either an odd or an even number. 


partition 

An area on a fixed disk set aside for a specific purpose, such as a location for 
an operating system. 

peripheral 


An external input/output, or storage device. 


pixel 


The acronym for picture element. A pixel is a single dot on a monitor that can 
be addressed by a single bit. 


port 


The entry channel to and from the central computer for connection of a 
communications line or other peripheral device. 


power 


The functional area of a system that transforms an external power source into 
internal DC supply voltage. 


program 


A series of instructions or statements in a form acceptable to a computer, 
designed to cause the computer to execute a series of operations. Computer 
programs include software such as operating systems, assemblers, compilers, 
interpreters, data management systems, utility programs, sort-merge programs, 
and maintenance/diagnostic programs, as well as application programs such as 
payroll, inventory control, and engineering analysis programs. 
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prompt 


A character or series of characters that appear on the screen to request input 
from the user. 


RAM 


Acronym for random-access memory. 


radian 


The natural unit of measure of the angle between two intersecting half-lines on 
the angles from one half-line to another intersecting half-line. It is the angle 
subtended by an arc of a circle equal in length to the radius of the circle. As the 
circumference of a circle is equal to 2 x times its radius, the number of radians 
in an angle of 360° or in a complete turn is 2 n. 


radix 


A number that is arbitrarily made the fundamental number of a system of 
numbers; a base. Thus, 10 is the radix, or base, of the common system of 
logarithms, and also of the decimal system of enumeration. 


random-access memory 


The system’s high-speed work area that provides access to memory storage 
locations by using a system of vertical and horizontal coordinates. The 
computer can write information into or read information from the random- 
access memory. Random-access memory is often called RAM. 


raster unit 


On a graphic display screen, a raster unit is the horizontal or vertical distance 
between two adjacent addressable points on the screen. 


read-only memory 


A type of memory that contains permanent data or instructions. The computer 
can read from but not write to the read-only memory. Read-only memory is 
often called ROM. 


real number 


An ordinary number, either rational or irrational; a number in which there is no 
imaginary part, a number generated from the single unit, 1; any point in a 
continuum of natural numbers filled in with all rationals and all irrationals and 
extended indefinitely, both positive and negative. 
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real time 

1. The actual time required to solve a problem. 

2. The process of solving a problem during the actual time that a related 
physical process takes place so that results can be used to guide the 
physical process. 

remote 


A term used to refer to devices that are located at sites away from the central 
computer. 


reverse video 
A display of characters on a background, opposite of the usual display. 


ROM 
Acronym for read-only memory. 


RS-232 


A standard communications interface between a modem and terminal devices 
that complies with EIA Standard RS-232. 


serial output 


Sending only one bit at a time to and from interconnected devices. 


single-density 


The standard recording density of a diskette. Single-density diskettes can store 
approximately 3400 bits per inch (bpi). 


single-precision value 


The number of words or storage positions used to denote a number in a 
computer. Single-precision arithmetic is the use of one word per number, 
double-precision arithmetic is the use of two words per number, and so on. For 
variable word-length computers, precision is the number of digits used to 
denote a number. The higher the precision, the greater the number of decimal 
places that can be carried. 


single-sided 


A term used to describe a diskette that contains data on one side only. 
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software 


A string of instructions that, when executed, direct the computer to perform 
certain functions. 


stack architecture 


An architecture wherein any portion of the external memory can be used as a 
last-in, first-out stack to store/retrieve the contents of the accumulator, the 
flags, or any of the data registers. Many units contain a 16-bit stack pointer to 
control the addressing of this external stack. One of the major advantages of 
the stack is that multiple-level interrupts can be handled easily, since complete 
system status can be saved when an interrupt occurs and then be restored after 
the interrupt. Another major advantage is that almost unlimited subroutine 
nesting is possible. 

statement 

A high-level language instruction to the computer to perform some sequence 
of operations. 

synchronous 


A type of computer operation in which the execution of each instruction or 
each event is controlled by a clock signal: evenly spaced pulses that enable the 
logic gates for the execution of each logic step. A synchronous operation can 
cause time delays by causing waiting for clock signals although all other 
signals at a particular logic gate were available. See asynchronous. 

switch 

An instruction, added to a command, that designates a course of action, other 
than default, for the command process to follow. 

syntax 


Rules of statement structure in a programming language. 


system 


A collection of hardware, software, and firmware that is interconnected to 
operate as a unit. 


task 


A machine run; a program in execution. 


toggle 


Alteration of function between two stable states. 
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track 

A specific area on a moving-storage medium, such as a diskette, disk, or tape 
cartridge, that can be accessed by the drive heads. 

tree-structured directory 

A file-organization structure, consisting of directories and subdirectories that, 
when diagrammed, resembles a tree. 

truncation 

To end a computation according to a specified rule; for example, to drop 
numbers at the end of a line instead of rounding them off, or to drop characters 
at the end of a line when a file is copied. 

upgrade 


To expand a system by installing options or using revised software. 


utility function 

Computer programs, dedicated to one particular task, that are helpful in using 
the computer. For example, FDISK, for setting up partitions on the fixed disk. 
variable 


A quantity that can assume any of a set of values as a result of processing data. 


volume label 


The name for the contents of a diskette or a partition on a fixed disk. 


word 


The set of bits comprising the largest unit that the computer can handle in a 
single operation. 


write-protect notch 


A cut-out opening in the sealed envelope of a diskette that, when covered, 
prevents writing or adding text to the diskette, but allows information to be 
read from the diskette. 


Index 


Array 

defined, 6.6 

size limits, 6.7 
ASCII character codes, C.1 
Asynchronous, 3 


Bad file mode, A.5 

Bad file number, A.5 
Bad filename, A.6 

Bad record number, A.6 


/c switch, 2.5 
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assembly language interface, D.1 
syntax, D.2 
Can't continue, A.3 
Command 
defined, 2.9 
kill, 5.3 
load, 5.3 
merge, 5.3 
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tun, 5.3 
save, 5.3 
Communication 
asynchronous 
defined, 3 
support, F.1 
GET statement, F.4 
I/O functions, F.2 
I/O statements, F.1 


Communication (continued) 
INPUTS function, F.3 
opening files, F.1 
possible errors, F.2 
PUT statement, F.4 

Communication buffer overflow, A.7 

Constants, numeric 
defined, 6.3 
double-precision defined, 6.4 
examples of double-precision, 6.5 
example of single-precision, 6.5 
single-precision defined, 6.4 

Constants, numeric 
types of, 6.3 

CTRL-6, 4.5 

CTRL-B, 4.5 

CTRL-BACKSPACE, 4.5 

CTRL-BREAK, 2.7, 4.5 

CTRL-C, 4.5 

CTRL-E, 4.6 

CTRL-END, 4.6 

CTRL-F, 4.5 

CTRL-G, 4.6 

CTRL-H, 4.5 

CTRL-HOME, 4.6 

CTRL-I, 4.7 

CTRL-J, 4.6 

CTRL-K, 4.6 

CTRL-L, 4.6 

CTRL-I, 4.5 

CTRL-M, 4.6 

CTRL-N, 4.6 
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CTRL-NUM LOCK, 4.7 
CTRL-PRTSC, 4.7 
CTRL-R, 4.6 

CTRL-S, 4.7 

CTRL-Z, 2.7 

CTRL-[, 4.6 

CTRL-], 4.5 

CTRLA, 4.5 
CURSOR-UP, 4.5 


/d switch, 2.6 
Delete a line, 3.6 
Device Fault, A.6 
Device I/O Error, A.8 
Device Timeout, A.6 
Device Unavailable, A.9 
Direct statement in file, A.8 
Disk full, A.8 
Disk media error, A.8 
Disk not Ready, A.8 
Division by zero, A.2 
Duplicate Definition, A.2 
EDIT command 
keys used with, 3.7 
EDLIN command 
example, 3.6 
ESC key, 4.6 
Expression, 6.10 


f switch, 2.5 

F1 key, 3.6 

F2 key, 3.6 

F3 key, 3.8 

F4 key, 3.7 

FIELD overflow, A.5 

File already exists, A.6 

File already open, A.5 

File not found, A.S 

FOR Without NEXT, A.4 

Function 
used with random access file, 5.8 
used with sequential files, 5.4 


Function keys 
assignments, 4.8 
defined, 4.8 
reassigned, 4.8 
shown on screen, 2.3 

Function, numeric, 2.9 

Function, string, 2.10 


GW-BASIC 
assembly language interface, D.1 
loading, 2.3 
memory available, 2.3 
special characters recognized, I.1 
GW-BASIC command 
examples, 2.6 
parameters described, 2.4 
redirected, 2.5, 2.8 
syntax, 2.4 
GW-BASIC, converting to 
FOR-NEXT loops, E.3 
MAT functions, E.2 
multiple assignments, E.2 
multiple statements, E.2 
string dimensions, E.1 


Ilegal function call, A.1 
Input past end, A.6 
Insert mode, 4.6 
Internal error, A.5 


Keyword, 2.8 
KILL command, 5.3 


Line, 3.6 

Line buffer overflow, A.4 
LIST command, 3.5 
LOAD command, 5.3 


f/m switch, 2.6 
Memory 
allocation for assembly language, D.1 
needed for storage, 6.8 
MERGE command, 5.3 
Missing operand, A.4 
Modes 
direct 
examples, 3.3 
uses of, 2.4 
indirect 
examples, 3.4 
uses of, 2.4 
insert, 4.6 


NAME command, 5.3 
No RESUME, A.3 


OPEN COM statement, F.1 
Operator 

defined, 15 
Operators 

arithmetic, 6.10 

defined, 6.10 

four categories, 6.10 

functional, 6.16 

logical, 6.13 

relational, 6.13 

string, A.1 
Out of DATA, A.1 
Out of memory, A.2 
Out of paper, A.4 
Out of string space, A.3 
Overflow, A.2 
Path not found, A.8 
Path/File Access Error, A.8 
Permission Denied, A.7 
Program 

distinguished from calculation, 3.5 
Program line 

format, 2.10 

format requirements, 2.11 


Index 3 


Quitting GW-BASIC, 2.12 


Random access file 
accessing, 5.9 
defined, 5.4 
example, 5.9, 5.10, 5.11 
functions used with, 5.8 
program steps required, 5.8 
statements used with, 5.8 
Recall a program file, 3.8 
Redirection, 2.8 
Rename across disks, A.8 
Reserved word. See Keyword 
RESUME without error, A.4 
RETURN without GOSUB, A.1 
RUN command, 5.3 
used in indirect mode, 2.4 


/s switch, 2.5 
Save a program file, 3.7 
SAVE command, 5.3 
Sequential file 
accessing, 5.6 
adding data, 5.7 
defined, 5.4 
example, 5.5, 5.6, 5.7 
functions used with, 5.4 
program steps required, 5.4 
statements used with, 5.4 
SHIFT-PRTSC 
prints screen, 4.7 
Statement, 19 
CALL, D.2 
defined, 2.9, 2.10 
OPEN COM, F.1 
used with random access file, 5.8 
used with sequenual files, 5.4 
String constant 
defined, 6.3 
String formula too complex, A.3 
String too long, A.3 
Subscript out of range, A.2 
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Switch 

Ic, 2.5 

/d, 2.6 

ff, 2.5 

/m, 2.6 

/s, 2.5 

specifying numbers for, 2.6 
Syntax error, A.1 


TAB key, 4.7 

Too many files, A.7 

TTY sample program, F.5 
notes on, F.6 

Type mismatch, A.3 


Undefined line number, A.2 
Undefined user function, A.3 
Unprintable error, A.4, A.5, A.6 
USR function call, D.1 

syntax, D.7 


Variable 
array defined, 6.6 
conversion done by GW-BASIC, 6.8 
declaration symbols, 6.6 
four types of, 6.6 
memory storage requirements, 6.8 
samples, 6.6 
Variable, fielded string 
not used in INPUT or LET 
statements, 5.9 
Variables 
defined, 2.10 


WEND without WHILE, A.5 
WHILE without WEND, A.4 
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introduction 


This manual is an alphabetical reference to Gw-BASic instructions: statements, 
functions, commands, and variables. 


The name and type of each instruction is listed at the top of the page, and is 
followed by: 


Purpose The purpose of the instruction 

Syntax The complete notation of the instruction 

Comments Pertinent information about the instruction, and what 
happens when it is encountered by GW-BASIC 

Examples An illustration of the instruction as it might appear in a 
program 


Notes Any special inforriation about the instruction 
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ABS Function 


Purpose: 


To return the absolute value of the expression n. 


Syntax: 

ABS(n) 

Comments: 

n must be a numeric expression. 


Examples: 


PRINT ABS (7* (-5)) 
35 
Ok 


Prints 35 as the result of the action. 
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ASC Function 


Purpose: 


To return a numeric value that is the ascu code for the first character of the 
string x$. 


Syntax: 


ASC/(x$) 


Comments: 


If x$ is null, an "Ilegal Function Call” error is returned. 


If x$ begins with an uppercase letter, the value returned will be within the 
range of 65 to 90. 


If x$ begins with a lowercase letter, the range is 97 to 122. 
Numbers 0 to 9 return 48 to 57, sequentially. 

See the CHR$ function for ascu-to-string conversion. 

See Appendix C in the GW-BASIC User's Guide for ascii codes. 


Examples: 


10 X$="TEN" 
20 PRINT ASC (XS) 
RUN 
84 
Ok 


84 is the ascu code for the letter T. 
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ATN Function 


Purpose: 


To return the arctangent of x, when x is expressed in radians. 


Syntax: 


ATN(x) 


Comments: 


The result is within the range of -n/2 to 1/2. 


The expression x may be any numeric type. The evaluation of ATN is 
performed in single precision unless the /d switch is used when Gw-BAsIc is 
executed. 


To convert from degrees to radians, multiply by 7/180. 


Examples: 


10 INPUT X 

20 PRINT ATN (X) 
RUN 

? 3 

1.249046 

Ok 


Prints the arctangent of 3 radians (1.249046). 
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AUTO Command 


Purpose: 


To generate and increment line numbers automatically each time you press the 
RETURN key. 


Syntax: 


AUTO [line number][,[increment]]} 
AUTO |[,[increment}] 


Comments: 


AUTO is useful for program entry because it makes typing line numbers 
unnecessary. 


AUTO begins numbering at line number and increments each subsequent line 
number by increment . The default for both values is 10. 


The period (.) can be used as a substitute for line number to indicate the current 
line. 

If line number is followed by a comma, and increment is not specified, the last 
increment specified in an AUTO command is assumed. 


If AUTO generates a line number that is already being used, an asterisk appears 
after the number to warn that any input will replace the existing line. However, 
pressing RETURN immediately after the asterisk saves the line and generates 
the next line number. 


AUTO is terminated by entering CTrRL-BREAK OF CTRL-C. GW-BASIC will then return 
to command level. 


Note The line in which crr_-BREAK Or CTRL-C is entered is not saved. To be sure 
that you save all desired text, use CTRL-BREAK and cTRL-c only on lines by 
themselves. 
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Examples: 


AUTO 100,50 
Generates line numbers 100, 150, 200, and so on. 
AUTO 


Generates line numbers 10, 20, 30, 40, and so on. 
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BEEP Statement 


Purpose: 


To sound the speaker at 800 Hz (800 cycles per second) for one-quarter of a 
second. 


Syntax: 


BEEP 


Comments: 


BEEP, crru-c, and PRINT CHR$(7) have the same effect. 


Examples: 


2340 IF X>20 THEN BEEP 


If X is out of range, the computer beeps. 


8 GW-BASIC User's Reference 


BLOAD Command 


Purpose: 


To load an image file anywhere in user memory. 


Syntax: 
BLOAD filename[,offset] 


Comments: 


filename is a valid string expression containing the device and filename. 


offset is a valid numeric expression within the range of 0 to 65535. This is the 
offset into the segment, declared by the last DEF SEG statement, where loading 
is LO Start. 


If offset is omitted, the offset specified at BSAVE is assumed; that is, the file is 
loaded into the same location it was saved from. 


Note BLOAD does not perform an address range check. It is possible to 
BLOAD anywhere in memory. You must not BLOAD over the cw-Basic stack 
space, a GW-BASIC program, or the Gw-Basic variable area. 


While BLOAD and BSAVE are useful for loading and saving machine 
language programs, they are not restricted to them. The DEF SEG statement 
lets you specify any segment as the source or target for BLOAD and BSAVE. 
For example, this allows the video screen buffer to be read from or written to 
the diskette. BLOAD and BSAVE are useful in saving and displaying graphic 
images. 
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Examples: 


10 DEF SEG=&HB800 
20 BLOAD"PICTURE", 0 


The DEF SEG statement in line 10 points the segment at the screen buffer. 


The DEF SEG statement in line 10 and the offset of 0 in line 20 guarantee that 
the correct address is used. 

The BLOAD command in line 20 loads the file named picture into the screen 
buffer. 


Note The BSAVE example in the next section illustrates how the file named 
picture is saved. 
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BSAVE Command 


Purpose: 

To save portions of user memory on the specified device. 
Syntax: 

BSAVE filename, offset,length 

Comments: 


filename is a valid string expression containing the filename. 

offset is a valid numeric expression within the range of 0 to 65535. This is the 
offset into the segment, declared by the last DEF SEG, where saving is to start. 
length is a valid numeric expression within the range of 0 to 65535, specifying 
the length of the memory image to be saved. 

If filename is less than one character, a "Bad File Number” error is issued and 
the load is aborted. 


Execute a DEF SEG statement before the BSAVE. The last known DEF SEG 
address is always used for the save. 


The DEF SEG statement must be used to set up the segment address to the start 
of the screen buffer. An offset of 0 and a length of 16384 specify that the entire 
16K screen buffer is to be saved. 


Examples: 


10 DEF SEG=&HB800 
20 BSAVE"PICTURE",0,16384 


The DEF SEG statement in line 10 points the segment at the screen buffer. 


The BSAVE command in line 20 saves the screen buffer in the file named 
picture. 
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CALL Statement 


Purpose: 


To call an assembly (or machine) language subroutine. 


Syntax: 


CALL numvar[(variables)] 


Comments: 


numvar is the starting point in memory of the subroutine being called as an 
offset into the current segment. 

variables are the variables or constants, separated by commas and enclosed in 
parentheses, that are to be passed to the routine. 

The CALL statement is recommended for interfacing assembly language 
programs with cw-sasic. Although the USR function may also be used, CALL 
is compatible with more languages, produces a more readable source code, and 
can pass multiple arguments. 


Invocation of the CALL statement causes the following to occur: 


e — Each parameter location in the variable is pushed onto the stack. The 
parameter location is a 2-byte offset into Gw-Basic’s data segment. 


o The return address code segment (CS) and the offset are pushed onto the 
stack. 


e Control is transferred to the user routine by the segment address given in 
the last DEF SEG statement and the offset given in the variable name. 


e The user routine now has control. Parameters may be referenced by 
moving the stack pointer (SP) to the base pointer (BP) and adding a 
positive offset to BP. 

e The called routine may destroy the contents of any registers. 

e The called program must know how many parameters were passed. 
Parameters are referenced by adding a positive offset to BP, assuming the 


called routine moved the current stack pointer into BP (that is, MOV 
BP,SP). 
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e The called program must know the variable type for numeric parameters 
passed. 


e The called routine must do a RET n, where n is the number of parameters 
in the variable times 2. This is necessary in order to adjust the stack to the 
point at the start of the calling sequence. 


e — Values are returned to cw-nasic by including in the argument list the name 
of the variable that is to receive the result. 


e If the argument is a string, the parameter offset points to three bytes 
called the string descriptor. Byte 0 of the string descriptor contains the 
length of the string (0 to 255). Bytes 1 and 2, respectively, are the lower- 
and upper-eight bits of the string starting address in the string space. 

e Ifthe argument is a string literal in the program, the string descriptor 
points to program text. Be careful not to alter or destroy a program this 
way. To avoid unpredictable results, add +"" to the string literal in the 
program, as in the following: 


20 A$="BASIC"+"" 


This forces the string literal to be copied into the string space. Now the 
string may be modified without affecting the program. 


Note Strings may be altered by user routines, but their length must not be 
changed. Gw-BAsic cannot correctly erase strings if their lengths are modified by 
external routines. 


For more information on the CALL statement and USR function, see 
Appendix D in the GW-BASIC User's Guide. 


Example 1: 


100 DEF SEG=&H2000 
110 ARK=0 
120 CALL ARK (A,B$,C) 
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Line 100 sets the segment to hex 2000. ARK is set to zero so that the call to 
ARK executes the subroutine at location 2000:0. 


Example 2: 


The following sequence of 8086 Assembly Language demonstrates access of 
the parameters passed and stored in variable C: 


PUSH BP 

MOV BP,SP ; Gets current stack position in BP. 
MOV BX, 8[BP] ; Gets address of B$ descriptor. 

MOV CL, [BX] ; Gets length of B$ in CL. 

MOV DX, 1[BX] ; Gets address of B$ text in DX. 

MOV SI,10[BP] ; Gets address of A in SI. 

MOV DI, 6[BP] ; Gets pointer to C in DI. 

MOVSW ; Stores variable A in C. 

RET 6 ; Restores stack and returns. 


MOVSW copies only two bytes. This is sufficient if variables A and C are 
integer. Four bytes must be copied if they are single precision; eight bytes, if 
they are double precision. 


Example 3: 


100 DEF SEG=&H2000 
110 ACC=&H7FA 
120 CALL ACC (A,B$,C) 


Line 100 sets the segment to hex 2000. The value of variable ACC is added 
into the address as the low word after the DEF SEG value is shifted four bits to 
the left (this is a function of the microprocessor, not of Gw-Basic). Here, ACC is 
set to &H7FA, so that the call to ACC executes the subroutine at the location 
hex 2000:7FA (absolute address hex 207FA). 
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CDBL Function 


Purpose: 


To convert x to a double-precision number. 


Syntax: 


CDBL(x) 


Comments: 


X must be a numeric expression. 


Example: 

10 A=454.67 

20 PRINT A;CDBL (A) 

RUN 

454.67 454.6700134277344 
Ok 


Prints a double-precision version of the single-precision value stored in the 
variable named A. 


The last 11 numbers in the double-precision number have no meaning in this 
example, since A was previously defined to only two-decimal place accuracy. 


Note See the CINT and CSNG functions for converting numbers to integer 
and single-precision, respectively. 
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CHAIN Statement 


Purpose: 


To transfer control to the specified program and pass (chain) variables to it 
from the current program. 


Syntax: 


CHAIN[MERGE] filename[,[line][,[ALL][,DELETE range]]] 


Comments: 


MERGE overlays the current program with the called program. 


Note The called program must be an ascu file (previously saved with the a 
option) if it is to be merged (see the MERGE command). 


filename is the name of the program that is called to be chained to. The BAS 
extension is assumed unless another is specified. 


line is a line number or an expression that corresponds to a line number in the 
called program. It is the starting point for execution of the called program. For 
example the following begins execution of PROG] at line 1000: 


10 CHAIN "PROG1", 1000 


If line is omitted, execution begins at the first line. 


line is not affected by a RENUM command. However, the line numbers in the 
specified range are affected by a RENUM command. 


ALL specifies that every variable in the current program is chained to the 
called program. For example: 


20 CHAIN "PROG1",1000,ALL 
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If the ALL option is omitted, the current program must contain a COMMON 
statement to list the variables that are passed. 

CHAIN executes a RESTORE before it runs the program that it is to be chained 
to. The READ statement then gets the first item in the DATA statement. 
Reading will not resume where it left off in the program that is being chained. 
After an overlay is executed and used for a specific purpose, it is usually 
desirable to delete it so that a new overlay may be brought in. To do this, use 
the DELETE command. 

The CHAIN statement with the MERGE command leaves the files open and 
preserves the current option base setting. 

If the MERGE command is omitted, the OPTION BASE setting is preserved, 
and CHAIN preserves no variable types or user-defined functions for use by the 
chained program. That is, aay DEFINT, DEFSNG, DEFDBL, DEFSTR, or 
DEF FN statement containing shared variables must be restated in the chained 
program. 

When using the merge command, place user-defined functions before any 


CHAIN MERGE statements in the program. Otherwise, they will be undefined 
after the merge is complete. 
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CHDIR Command 


Purpose: 


To change from one working directory to another. 


Syntax: 


CHDIR pathname 


Comments: 


pathname is a string expression of up to 63 characters. 


To make sales the working directory on Drive A: and inventory the working 
directory on Drive B: (assume A: is the default drive), type the following 
commands: 


CHDIR "SALES" 
CHDIR "B: INVENTORY" 
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CHR$ Function 
Purpose: 


To convert an asci code to its equivalent character. 


Syntax: 


CHR§$(n) 


Comments: 


nis a value from 0 to 255. 


CHR$ is commonly used to send a special character to the terminal or printer. 
For example, you could send CHR$(7) to sound a beep through the speaker as a 
preface to an error message, or you could send a form feed, CHR$(12), to the 
printer. 


See the ASC function for ascn-to-numeric conversion. 
asci Codes are listed in Appendix C of the GW-BASIC User's Guide. 


Examples: 


PRINT CHRS (66); 
B 
Ok 


This prints the ascu character code 66, which is the uppercase letter B. 
PRINT CHRS$ (13); 


This command prints a carriage return. 
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CINT Function 


Purpose: 


To round numbers with fractional portions to the next whole number or integer. 


Syntax: 


CINT(x) 


Comments: 
If x is not within the range of -32768 to 32767, an “Overflow” error occurs. 


See the FIX and INT functions, both of which return integers. 


Examples: 


PRINT CINT (45.67) 
46 
Ok 


45.67 is rounded up to 46. 


Note See the CDBL and CSNG functions for converting numbers to the 
double-precision and single-precision data types, respectively. 
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CIRCLE Statement 


Purpose: 


To draw a circle, ellipse, and angles on the screen during use of the Graphics 
mode. 


Syntax: 


CIRCLE(xcenter,ycenter),radius|,[color][,[start],[end]{,aspect]}] 


Comments: 


xcenter and ycenter are the x- and y- coordinates of the center of the ellipse, 
and radius is the radius (measured along the major axis) of the ellipse. The 
quantities xcenter and ycenter can be expressions. The center attributes can use 
either absolute or relative coordinates. 


color specifies the color of the ellipse. Its value depends on the current screen 
mode. 


See the COLOR and SCREEN statements for more information on using colors 
in different screen modes. 


In the high-resolution mode, 0 indicates black and 1 indicates white. The 
default for the high resolution mode is 1. 


The start and end angle parameters are radian arguments between -2*x and 2*1 
which specify where the drawing of the ellipse is to begin and end. If start or 
end is negative, the ellipse is connected to the center point with a line, and the 
angles are treated as if they are positive (note that this is different from adding 
2*n). 

aspect describes the ratio of the x radius to the y radius (x:y). The default 
aspect ratio depends on the screen mode, but gives a visual circle in either 
graphics mode, assuming a standard monitor screen aspect ratio of 4:3. 


If the aspect ratio is less than 1, then the radius is given in x-pixels. If it is 
greater than 1, the radius is given in y-pixels. 
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In many cases, an aspect ratio of 1 gives better ellipses in the medium- 
resolution mode. This also causes the ellipse to be drawn faster. The start angle 
may be less than the end angle. 


Example 1: 


10 SCREEN1: CIRCLE(100,100), 50 
Draws a circle of radius 50, centered at graphics points 100x and 100y. 


Example 2: 


1’ This will draw 17 ellipses 
10 CLS 

20 SCREEN 1 

30 FOR R=160 TO 0 STEP-10 

40 CIRCLE (160,100),R,,,,5/18 
50 NEXT 


Example 3: 


10 ‘This will draw 5 spheres 

20 GOTO 160 

50 IF VERT GOTO 100 

60 CIRCLE (X,Y),R,C,,,.07 

70 FOR I =1T0 5 

80 CIRCLE (X,Y),R,C,,,1*.2:NEXT I 
90 IF VERT THEN RETURN 
100 CIRCLE (X,Y),R,C,,,1. 
110 CIRCLE (X,Y),R,C,,,1. 
120 CIRCLE (X,Y),R,C,,,3. 
130 CIRCLE (X,Y),R,C,,,9. 
140 IF VERT GOTO 60 

150 RETURN 

160 CLS:SCREEN 1:COLOR 0,1:KEY OFF: VERT=0 
170 X=160:Y=100:C=1:R=50:GOSUB 50 

180 X=30:Y=30:C=2:R=30:GOSUB 50 

190 X=30:Y=169:GOSUB 50 

200 X=289:Y=30:GOSUB 50 

210 X=289:Y=169:GOSUB 50 

220 LINE (30, 30)-(289,169),1 

230 LINE (30,169) -(289,30),1 

240 LINE (30,169)-(289,30),1,B 

250 ZS=INKEYS$: IF Z$="" THEN 250 

RUN 


3 
9 
6 
8 
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CLEAR Command 


Purpose: 


To set all numeric variables to zero, all string variables to null, and to close all 
open files. Options set the end of memory and reserve the amount of string and 
stack space available for use by Gw-BASIc. 


Syntax: 


CLEAR[,[expression! ]{,expression2]] 


Comments: 


expression! is amemory location that, if specified, sets the maximum number 
of bytes available for use by Gw-BAsIc. 


expression2 sets aside stack space for cw-pasic. The default is the previous 
stack space size. When cw-sasic is first executed, the stack space is set to 512 
bytes, or one-eighth of the available memory, whichever is smaller. 


Gw-BAsic allocates string space dynamically. An "Out of String Space” error 
occurs only if there is no free memory left for Gw-Basic to use. 


The CLEAR command: 

e = Closes all files 

e Clears all COMMON and user variables 
e Resets the stack and string space 

e Releases all disk buffers 

e Tums off any sound 

e _ Resets sound to music foreground 

e — Resets PEN to off 

e Resets STRIG to off 

e Disables ON ERROR trapping 
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Examples: 


CLEAR 
Zeroes variables and nulls all strings. 
CLEAR 32768 


Zeroes variables, nulls strings, protects memory above 32768, does not change 
the stack space. 


CLEAR ,,2000 


Zeroes variables, nulls strings, allocates 2000 bytes for stack space, and uses all 
available memory in the segment. 


CLEAR ,32768,2000 


Zeroes variables, nulls strings, protects memory above 32768, and allocates 
2000 bytes for stack space. 
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CLOSE Statement 
Purpose: 


To terminate input/output to a disk file or a device. 


Syntax: 


CLOSE [[#]ftlenumber[,[#]filenumber]...] 


Comments: 


filenumber is the number under which the file was opened. 


The association between a particular file or device and file number terminates 
upon execution of a CLOSE statement. The file or device may then be 
reopened using the same or a different file number. 


A CLOSE statement with no file number specified closes all open files and 
devices. 


A CLOSE statement sent to a file or device opened for sequential output writes 
the final buffer of output to that file or device. 


The END, NEW, RESET, SYSTEM, or RUN and LOAD (without r option) 
statements always close all files or devices automatically. STOP does not close 
files. 


Examples: 


250 CLOSE 
This closes all open devices and files. 
300 CLOSE 1, #2, #3 


Closes all files and devices associated with file numbers 1, 2, and 3. 
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CLS Statement 
Purpose: 


To clear the screen. 


Syntax: 
CLS [n] 


Comments: 


nis one of the following values: 


Valueofn Effect 


0 Clears the screen of all text and graphics 
1 Clears only the graphics viewport 
2 Clears only the text window 


If the graphics viewport is active, CLS without argument clears only the 
viewport. If the graphics viewport is inactive, CLS clears the text window. 


If the screen is in alpha mode, the active page is cleared to the currently 
selected background color (see the SCREEN and COLOR statements). 


If the screen is in graphics mode, the entire screen buffer is cleared to 
background color. 


The screen may also be cleared by pressing CTRL-HOME, or by changing the 
screen mode with the SCREEN or WIDTH statements. 


CLS returns the cursor to the upper-left corner of the screen, and sets the last 
point referenced to the center of the screen. 


If the VIEW statement has been used, CLS clears only the last viewport 
specified. 
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Examples: 


1 CLS 


This clears the screen. 
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COLOR Statement 


Purpose: 


To select display colors. 


Syntax: 


COLOR [foreground] [,[background]|[,border}] 
COLOR [background][,[palette)]} 
COLOR [foreground][,[background]] 


Comments: 


In general, COLOR allows you to select the foreground and background colors 
for the display. In SCREEN 0 a border color can also be selected. In SCREEN 
1 no foreground color can be selected, but one of two four-color palettes can be 
selected for use with graphics statements. The different syntaxes and effects 
that apply to the various screen modes are described below: 


Mode Effect 


SCREEN 0 Modifies the current default text foreground and background 
colors, and the screen border. The foreground color must be an 
integer expression in the range 0-31. It is used to determine the 
"foreground" color in text mode, which is the default color of 
text. Sixteen colors can be selected with the integers 0-15. A 
blinking version of each color can be selected by adding 16 to 
the color number; for example, a blinking color 7 is equal to 7 + 
16, or 23. Thus, the legal integer range for foreground is 0-31. 


The background color must be an integer expression in the range 
0-7, and is the color of the background for each text character. 
Blinking colors are not permitted. 


The border color is an integer expression in the range 0-15, and 
is the color used when drawing the screen border. Blinking 
colors are not permitted. 
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If no arguments are provided to COLOR, then the default color 
for background and border is black (color 0), and for 
foreground, is as described in the SCREEN statement reference 
pages. 

SCREEN 1 In mode 1, the COLOR statement has a unique syntax that 
includes a palette argument, which is an odd or even integer 
expression. This argument determines the set of display colors to 
use when displaying particular color numbers. 


For hardware configurations that do not have an IBM® 
Enhanced Graphics Adapter (EGA), the default color settings 
for the palette parameter are equivalent to the following: 


COLOR ,0 ‘Same as the next three 
PALETTE ‘statements 
‘1 = green, 2 = red, 
‘3 = yellow 
COLOR ,1 ‘Same as the next three 
PALETTE ‘statements 
‘1 = cyan, 2 = magenta, 
‘3 = hi. 


‘intens. white 


With the EGA, the default color settings for the palette 
parameter are equivalent to the following: 


COLOR ,0 ‘Same as the next three 

PALETTE ‘statements 

PALETTE 1,2 ‘Attribute 1 = color 3 
* (green) 

PALETTE 2,4 ‘Attribute 2 = color 5 
‘ (red) 

PALETTE 3,6 ‘Attribute 3 = color 6 
* (brown) 

COLOR ,1 ‘Same as the next three 

PALETTE ‘statements 

PALETTE 1,3 ‘Attribute 1 = color 3 
’ (cyan) 


PALETTE 2,5 ‘Attribute 2 = color 5 
‘ (magenta) 
PALETTE 3,7 ‘Attribute 3 = color 15 
‘ (white) 
Note that a COLOR statement will override previous PALETTE 
statements. 


SCREEN 2 No effect. An "Ilegal function call" error message occurs if 
COLOR is used in this mode. 
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SCREEN 7- In these modes, no border color can be specified. The 

SCREEN 10 graphics background is given by the background color 
number, which must be in the valid range of color numbers 
appropriate to the screen mode. See the SCREEN statement 
reference pages for more details. The foreground color 
argument is the default line drawing color. 


Arguments outside valid numeric ranges result in "Illegal function call” errors. 
The foreground color may be the same as the background color, making 


displayed characters invisible. The default background color is black, or color 
number 0, for all display hardware configurations and all screen modes. 


With the Enhanced Graphics Adapter (EGA) installed, the PALETTE statement 
gives you flexibility in assigning different display colors to the actual color- 
number ranges for the foreground, background, and border colors discussed 
above. See the PALETTE statement reference pages for more details. 

For more information, see CIRCLE, DRAW, LINE, PALETTE, PAINT, 
PRESET, PSET, SCREEN 


Examples: 


The following series of examples show COLOR statements and their effects in 
the various screen modes: 


SCREEN 0 

COLOR 1, 2, 3 'foreground=1, background=2, 
‘border=3 

SCREEN 1 

COLOR 1,0 ‘foreground=1, even palette 
‘number 

COLOR 2,1 ‘ foreground=2, odd palette 
‘number 

SCREEN 7 

COLOR 3,5 ‘foreground=3, background=5 

SCREEN 8 

COLOR 6,7 ‘foreground=6, background=7 

SCREEN 9 


COLOR 1,2 ‘foreground=1, background=2 
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COM(n) Statement 


Purpose: 


To enable or disable trapping of communications activity to the specified 
communications adapter. 


Syntax: 


COM(n) ON 
COM(n) OFF 
COM(n) STOP 


Comments: 


nis the number of the communications adapter 1 or 2. 


Execute a COM(n) ON statement before ON COM(n) statement to allow 
trapping. After COM(n) ON, if a nonzero number is specified in the ON 
COM(n) statement, BASIC checks every new statement to see if any characters 
have come in the communication adapter. 


With COM(n) OFF, no trapping takes place, and all communications activity 
will be lost. 
With COM(n) STOP, no trapping takes place. However, any communication 


that takes place will be remembered so that immediate trapping will occur 
when COM(n) ON is executed. 
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COMMON Statement 


Purpose: 


To pass variables to a chained program. 


Syntax: 


COMMON variables 


Comments: 


variables are one or more variables, separated by commas, that you want to 
pass to the chained program. 


The COMMON statement is used in conjunction with the CHAIN statement. 


COMMON statements may appear anywhere in a program, although it is 
recommended that they appear at the beginning. 


Any number of COMMON statements may appear in a program, but the same 
variable cannot appear in more than one COMMON statement. To pass all 
variables using the CHAIN statement, use the all option, and omit the 
COMMON statement. Place parentheses after the variable name to indicate 
array variables. 


Examples: 


100 COMMON A, B, C, D(),G$ 
110 CHAIN "A:PROG3" 


This example chains to program PROG3 on disk drive A:, and passes the array 
D along with the variables A, B, C, and string G$. 
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CONT Command 


Purpose: 


To continue program execution after a break. 


Syntax: 


CONT 


Comments: 


Resumes program execution after crRL-BREAK, STOP, or END halts a program. 
Execution continues at the point where the break happened. If the break took 
place during an INPUT statement, execution continues after reprinting the 
prompt. 

CONT is useful in debugging, in that it lets you set break points with the STOP 
statement, modify variables using direct statements, continue program 
execution, or use GOTO to resume execution at a particular line number. 


If a program line is modified, CONT will be invalid. 
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COS Function 


Purpose: 


To return the cosine of the range of x. 


Syntax: 


COS(x) 


Comments: 


x must be the radians. COS is the trigonometric cosine function. To convert 
from degrees to radians, multiply by 1/180. 


COS(x) is calculated in single precision unless the /d switch is used when cw- 
BASIC 1s executed. 


Example 1: 


10 X=2*COS(.4) 
20 PRINT X 
RUN 

1.842122 

Ok 


Example 2: 


10 PI=3.141593 

20 PRINT COS (PI) 

30 DEGREES=180 

40 RADIANS=DEGREES*PI/180 
50 PRINT COS (RADIANS) 

RUN 

=] 

=1 

OK 
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CSNG Function 

Purpose: 

To convert x to a single-precision number. 
Syntax: 

CSNG(x) 


Comments: 


x must be a numeric expression (see the CINT and CDBL functions). 
Examples: 


10 A#=975.3421222+# 
20 PRINT A#; CSNG (A#) 
RUN 

975.3421222 975.3421 
Ok 
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CSRLIN Variable 


Purpose: 


To return the current line (row) position of the cursor. 


Syntax: 
y=CSRLIN 


Comments: 


y is a numeric variable receiving the value returned. The value returned is 
within the range of 1 to 25. 


The CSRLIN Variable returns the vertical coordinate of the cursor on the active 
page (see the SCREEN statement). 


x=POS(0) returns the column location of the cursor. The value returned is 
within the range of 1 to 40, or 1 to 80, depending on the current screen width 
(see the POS function). 


Examples: 


10 Y=CSRLIN 

20 X=POS (0) 

30 LOCATE 24,1 
40 PRINT "HELLO" 
50 LOCATE Y,X 
RUN 

HELLO 

Ok 


The CSRLIN Variable in line 10 records the current line. 
The POS function in line 20 records the current column. 


In line 40, the PRINT statement displays the comment "HELLO" on the 24th 
line of the screen. 


The LOCATE statement in line 50 restores the position of the cursor to the 
original line and column. 
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CVI, CVS, CVD Functions 


Purpose: 


To convert string values to numeric values. 


Syntax: 


CVI(2-byte string) 
CVS(4-byte string) 
CVD(8-byte string) 


Comments: 


Numeric values read in from a random-access disk file must be converted from 
strings back into numbers if they are to be arithmetically manipulated. 

CVI converts a 2-byte string to an integer. MKI$ is its complement. 

CVS converts a 4-byte string to a single-precision number. MKSS$ is its 
complement. 


CVD converts an 8-byte string to a double-precision number. MKD$ is its 
complement. 


(See MKIS, MKS$, and MKD$). 


Examples: 


70 FIELD #1,4 AS N$, 12 AS BS... 
80 GET #1 
90 Y=CVS (NS) 
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Line 80 reads a field from file #1 (the field read is defined in line 70), and 
converts the first four bytes (N$) into a single-precision number assigned to the 
variable Y. 


Since a single-precision number can contain as many as seven ASCII 
characters (seven bytes), writing a file using MKS$ conversion, and reading 
with the CVS conversion, as many as three bytes per number recorded are 
saved on the storage medium. Even more may be saved if double-precision 
numbers are required. MKD§$ and CVD conversions would be used in this case. 
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DATA Statement 


Purpose: 


To store the numeric and string constants that are accessed by the program 
READ statement(s). 


Syntax: 


DATA constants 


Comments: 


constants are numeric constants in any format (fixed point, floating-point, or 
integer), separated by commas. No expressions are allowed in the list. 


String constants in DATA statements must be surrounded by double quotation 
marks only if they contain commas, colons, or significant leading or trailing 
spaces. Otherwise, quotation marks are not needed. 


DATA statements are not executable and may be placed anywhere in the 
program. A DATA statement can contain as many constants that will fiton a 
line (separated by commas), and any number of DATA statements may be used 
in a program. 

READ statements access the DATA statements in order (by line number). The 
data contained therein may be thought of as one continuous list of items, 
regardless of how many items are on a line or where the lines are placed in the 
program. The variable type (numeric or string) given in the READ statement 
must agree with the corresponding constant in the DATA statement, or a "Type 
Mismatch" error occurs. 


DATA statements may be reread from the beginning by use of the RESTORE 
statement. 


For further information and examples, see the RESTORE statement and the 
READ statement. 
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Example 1: 


80 FOR I=1 TO 10 

90 READ A(T) 

100 NEXT I 

110 DATA 3.08,5.19,3.12,3.98,4.24 
120 DATA 5.08,5.55,4.00,3.16,3.37 


This program segment reads the values from the DATA statements into array 
A. After execution, the value of A(1) is 3.08, and so on. The DATA statements 
(lines 110-120) may be placed anywhere in the program; they may even be 
placed ahead of the READ statement. 


Example 2: 


5 PRINT 

10 PRINT "CITY", "STATE", "ZIP" 

20 READ CS,S$,Z 

30 DATA "DENVER,", "COLORADO", 80211 
40 PRINT C$,S$,Z 


RUN 

CITY STATE ZIP 
DENVER, COLORADO 80211 
Ok 


This program reads string and numeric data from the DATA statement in line 
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DATE$ Statement and Variable 


Purpose: 


To set or retrieve the current date. 


Syntax: 


As a Statement: 
DATE$=v$ 


As a variable: 


v$=DATE$ 


Comments: 


v$ is a valid string literal or variable. 

v$ can be any of the following formats when assigning the date: 

mm-dd-yy 

mm/dd/yy 

mm_-dd-yyyy 

mm/dd/yyyy 

If v$ is not a valid string, a "Type Mismatch” error results. Previous values are 
retained. 

If any of the values are out of range or missing, an "Illegal Function Call" error 
is issued. Any previous date is retained. 

The current date (as assigned when the operating system was initialized) is 
fetched and assigned to the string variable if DATES is the expression in a LET 
or PRINT statement. 


The current date is stored if DATES is the target of a string assignment. 
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With v$=DATE$, DATES returns a 10-character string in the form mm- 
ddyyyy. mm is the month (01 to 12), dd is the day (01 to 31), and yyyy is the 
year (1980 to 2099). 


Examples: 


vS=DATES 
Ok 

PRINT V$ 
01-01-1985 
Ok 
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DEF FN Statement 


Purpose: 


To define and name a function written by the user. 


Syntax: 


DEF FNname[arguments] expression 


Comments: 


name must be a legal variable name. This name, preceded by FN, becomes the 
name of the function. 


arguments consists of those variable names in the function definition that are to 
be replaced when the function is called. The items in the list are separated by 
commas. 


expression is an expression that performs the operation of the function. It is 
limited to one statement. 


In the DEF FN statement, arguments serve only to define the function; they do 
not affect program variables that have the same name. A variable name used in 
a function definition may or may not appear in the argument. If it does, the 
value of the parameter is supplied when the function is called. Otherwise, the 
current value of the variable is used. 


The variables in the argument represent, on a one-to-one basis, the argument 
variables or values that are to be given in the function call. 


User-defined functions may be numeric or string. If a type is specified in the 
function name, the value of the expression is forced to that type before it is 
returned to the calling statement. If a type is specified in the function name and 
the argument type does not match, a "Type Mismatch” error occurs. 


A user-defined function may be defined more than once in a program by 
repeating the DEF FN statement. 
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A DEF FN statement must be executed before the function it defines may be 
called. If a function is called before it has been defined, an "Undefined User 
Function" error occurs. 


DEF FN is illegal in the direct mode. 
Recursive functions are not supported in the DEF FN statement. 


Examples: 


400 R=1:S=2 
410 DEF FNAB (X, Y) =X*3/Y%2 
420 T=FNAB (R, S) 


Line 410 defines the user-defined function FNAB. The function is called in line 
420. When executed, the variable T will contain the value R3 divided by S2, or 
.25. 
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DEFINT/SNG/DBL/STR Statements 


Purpose: 


To declare variable types as integer, single-precision, double-precision, or 
string. 


Syntax: 


DEF ype letters 


Comments: 


type is INT (integer), SNG (single-precision number), DBL (double-precision 
number), or STR (string of 0-255 characters). 


itletters are letters (separated by commas) or range of letters of the alphabet. 


A DEFtype statement declares that variable names beginning with the letter(s) 
specify that type of variable. However, a type declaration character (%,!,#,$) 
always takes precedence over a DEFtype statement in the typing of a variable. 


If no type declaration statements are encountered, BASIC assumes all variables 
are single-precision. Single-precision is the default value. 


Examples: 


10 DEFDBL L-P 


All variables beginning with the letters L, M, N, O, and P will be double- 
precision variables. 


10 DEFSTR A 
20 A="120#" 


All variables beginning with the letter A will be string variables. The $ 
declaration is unnecessary in this example. 


10 DEFINT I-N,W-Z 
20 WS="120#" 
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All variables beginning with the letters I, J, K, L, M, N, W, X, Y, Z will be 
integer variables. W$ in Line 20 establishes a string variable beginning with the 
letter W. However, the variable W will remain an integer elsewhere in the 
program. 
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DEF SEG Statement 


Purpose: 


To assign the current segment address to be referenced by a subsequent 
BLOAD, BSAVE, CALL, PEEK, POKE, or USR. 


Syntax: 


DEF SEG [=address] 


Comments: 


address is a numeric expression within the range of 0 to 65535. 

The address specified is saved for use as the segment required by BLOAD, 
BSAVE, PEEK, POKE, and CALL statements. 

Entry of any value outside the address range (0-65535) results in an “Illegal 
Function Call" error, and the previous value is retained. 

If the address option is omitted, the segment to be used is set to Gw-BAsic’s data 
segment (DS). This is the initial default value. 


If you specify the address option, base it on a 16-byte boundary. 


Segment addresses are shifted 4 bits to the left; so to get the segment address, 
divide the memory location by 16. 

For BLOAD, BSAVE, PEEK, POKE, or CALL statements, the value is shifted 
left four bits (this is done by the microprocessor, not by cw-Basic) to form the 
code segment address for the subsequent call instruction (see the BLOAD, 
BSAVE, CALL, PEEK, and POKE statements). 


Gw-Basic does not perform additional checking to assure that the resultant 
segment address is valid. 
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Examples: 

10 DEF SEG=&£HB800 

Sets segment to screen buffer. 

20 DEF SEG 

Restores segment to BASIC DS. 

Note DEF and SEG must be separated by a space. Otherwise, Gw-Basic will 


interpret the statement DEFSEG=100 to mean, "assign the value 100 to the 
variable DEFSEG.” 
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DEF USR Statement 


Purpose: 


To specify the starting address of an assembly language subroutine to be called 
from memory by the USR function. 


Syntax: 


DEF USR[n]=integer 


Comments: 


n may be any digit from 0 to 9. The digit corresponds to the USR routine 
address being specified. If n is omitted, DEF USRO is assumed. 

integer is the offset address of the USR routine. If more than 10 USR routines 
are required, DEF USR[n] may appear in the program as many times as 
necessary to redefine the USR[m] starting address. 

Add the current segment value to the integer to get the starting address of the 
user routine. 

When an Assembly Language Subroutine is called, the Gw-Basic program 
execution is paused, and control is transferred to the Assembly Language 
program. When that program is executed, control is returned to the Gw-BAsIc 
program at the point of interruption. 


Examples: 


190 DEF SEG=0 
200 DEF USRO=24000 
210 X=USRO (Y¥*%2/2. 82) 


Lines 190 and 200 set the absolute address. 
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Line 210 calls the USR routine located at that address, and passes the integer 
value of the expression contained within the parentheses to the user program 
(see USR). 


Note This statement is given here primarily to provide compatibility with 
other Gw-Basic implementations. The more versatile CALL statement should be 
used if this downward compatibility is unimportant. 
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DELETE Command 


Purpose: 


To delete program lines or line ranges. 


Syntax: 


DELETE [line number1]{-line number2] 
DELETE line number 1- 


Comments: 


line number! is the first line to be deleted. 
line number? is the last line to be deleted. 


Gw-BAsic always returns to command level after a DELETE command is 
executed. Unless at least one line number is given, an "Illegal Function Call" 
error occurs. 


The period (.) may be used to substitute for either line number to indicate the 
current line. 


Examples: 


DELETE 40 

Delctes line 40. 

DELETE 40-100 

Deletes lines 40 through 100, inclusively. 
DELETE -40 

Deletes all lines up to and including line 40. 
DELETE 40- 


Deletes all lines from line 40 to the end of the program. 


DIM Statement 51 





DIM Statement 


Purpose: 


To specify the maximum values for array variable subscripts and allocate 
storage accordingly. 


Syntax: 


DIM variable(subscripts)[,variable(subscripts)]... 


Comments: 


If an array variable name is used without a DIM statement, the maximum value 
of its subscript(s) is assumed to be 10. If a subscript greater than the maximum 
specified is used, a "Subscript out of range” error occurs. 


The maximum number of dimensions for an array is 255. 


The minimum value for a subscript is always 0, unless otherwise specified with 
the OPTION BASE statement. 


An array, once dimensioned, cannot be redimensioned within the program 
without first executing a CLEAR or ERASE statement. 


The DIM statement sets all the elements of the specified arrays to an initial 
value of zero. 


Examples: 


10 DIM A(20) 

20 FOR I=0 TO 20 
30 READ A (I) 

40 NEXT I 


This example reads 21 DATA statements elsewhere in the program and assigns 
their values to A(0) through A(20), sequentially and inclusively. If the A array 
is Single precision (default accuracy) then line 10 will allocate 84 bytes of 
memory to this array (4 bytes times 21 elements). 
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DRAW Statement 


Purpose: 


To draw a figure. 


Syntax: 


DRAW string expression 


Comments: 


The DRAW statement combines most of the capabilities of the other graphics 
statements into an object definition language called Graphics Macro Language 
(GML). A GML command is a single character within a string, optionally 
followed by one or more arguments. 


The DRAW statement is valid only in graphics mode. 


Movement Commands 


Each of the following movement commands begins movement from the current 
graphics position. This is usually the coordinate of the last graphics point 
plotted with another GML command, LINE, or PSET. The current position 
defaults to the center of the screen (160,100 in medium resolution; 320,100 in 
high resolution) when a program is run. Movement commands move for a 
distance of scale factor *n, where the default for n is 1; thus, they move one 
point if n is omitted and the default scale factor is used. 


Command Moves 


Un up 

Dn down 

Ln left 

Rn right 

En diagonally up and right 


Fn diagonally down and right 
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Gn diagonally down and left 
Hn diagonally up and left 


This command moves as specified by the following argument: 


Mx,y Move absolute or relative. If x is preceded by a + or -, x and y 
are added to the current graphics position, and connected to the 
current position by a line. Otherwise, a line is drawn to point x,y 
from the current position. 


The following prefix commands may precede any of the above movement 
commands: 


B Move, but plot no points. 

N Move, but retum to original position when done. 

The following commands are also available: 

An Set angle n. n may range from 0 to 3, where 0 is 0°, 1 is 90°, 2 is 
180°, and 3 is 270°. Figures rotated 90° or 270° are scaled so that 
they will appear the same size as with 0° or 180° on a monitor 
screen with the standard aspect ratio of 4:3. 

TAn Turn angle n. n can be any value from negative 360 to positive 
360. If the value specified by n is positive, it turns the angle 
counter-clockwise. If the value specified by n is negative, it 
turns clockwise. 


Cn Set color n. See the COLOR, PALETTE, and SCREEN 
statements for discussions of valid colors, numbers and 
attributes. 

Sn Set scale factor. n may range from 1 to 255. n is divided by 4 to 


derive the scale factor. The scale factor is multiplied by the 
distances given with U, D, L, R, E, F, G, H, or relative M 
commands to get the actual distance traveled. The default for S 


is 4. 
xstring; Execute substring. This command executes a 
variable second substring from a string, much like GOSUB. One string 


executes another, which executes a third, and so on. 


string is a variable assigned to a string of movement commands. 
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Ppaint, Specifies the colors for a graphics figure and 
boundary creates a filled-in figure. 


paint specifies what color you want the figure filled in with. 
boundary specifies the border color (outline). 


See the COLOR, PALETTE, and SCREEN statements for 
discussions of valid colors, numbers and attributes. 


You must specify values for both paint and boundary when 
used. 


This command (Ppaint,boundary) does not paint color tiling. 


Numeric Arguments: 
Numeric arguments can be constants like "123" or "=variable;", where variable 
is the name of a variable. 


When you use the second syntax, "=variable;", the semicolon must be used. 
Otherwise, the semicolon is optional between commands, 


You can also specify variables using VARPTRS$(variable). 


Example 1: 


To draw a box in medium resolution: « 


10 SCREEN 1 

20 A=20 

30 DRAW "U=A; R=A; D=A; L=A;" 
RUN 
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Example 2: 


The aspect ratio to draw a square on a standard screen is 4:3, as shown below: 


To draw a 96 pixel-wide square on a 640 x 200 pixel screen (SCREEN 2), do 
the following calculations: 

Horizontal value = 96 

Vertical value = 96*(200/640)*(4/3) 

or 

Vertical value = 40 

Horizontal value = 40*(640/200)*(3/4) 

The horizontal values equals 4/3 of the vertical values. 


Example 3: 


To draw a triangle in medium resolution: 


10 CLS 

20 SCREEN 1 

30 PSET (60,125) 

40 DRAW "E100; F100; L199" 
RUN 
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EDIT Command 


Purpose: 


To display a specified line, and to position the cursor under the first digit of the 
line number, so that the line may be edited. 


Syntax: 

EDIT line number 
EDIT. 
Comments: 


line number is the number of a line existing in the program. 


A period (.) refers to the current line. The following command enters EDIT at 
the current line: 


EDIT 


When a line is entered, it becomes the current line. 


The current line is always the last line referenced by an EDIT statement, LIST 
command, or error message. 


If line number refers to a line which does not exist in the program, an 
"Undefined Line Number” error occurs. 


Examples: 


EDIT 150 


Displays program line number 150 for editing. 
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END Statement 


Purpose: 


To terminate program execution, close all files, and return to command level. 
Syntax: 

END 

Comments: 


END statements may be placed anywhere in the program to terminate 
execution. 


Unlike the STOP statement, END does not cause a "Break in line xax" 
message to be printed. 


An END statement at the end of a program is optional. cw-Basic always returns 
to command level after an END is executed. END closes all files. 


Examples: 


520 IF K>1000 THEN END ELSE GOTO 20 


Ends the program and returns to command level whenever the value of K 
exceeds 1000. 
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ENVIRON Statement 


Purpose: 


To allow the user to modify parameters in Gw-BAsic’s environment string table. 
This may be to change the path parameter for a child process, (see ENVIRONS, 
SHELL, and the MS-DOS utilities PATH command), or to pass parameters to a 
child by inventing a new environment parameter. 


Syntax: 


ENVIRON string 


Comments: 


string is a valid string expression containing the new environment string 
parameter. 


string must be of the following form 
parmid=text 
where parmid is the name of the parameter such as PATH. 


parmid must be separated from text by an equal sign or a blank. ENVIRON 
takes everything to the left of the first blank or equal sign as the parmid; 
everything following is taken as text. 


text is the new parameter text. If text is a null string, or consists only of a single 
semicolon, then the parameter (including parmid=) is removed from the 
environment string table, and the table is compressed. text must not contain 
any embedded blanks. 


If parmid does not exist, then string is added at the end of the environment 
string table. 


If parmid does exist, it is deleted, the environment string table is compressed, 
and the new string is added at the end. 
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Examples: 


Assuming the environment string table is empty, the following statement will 
create a default path to the root directory on Disk A: 


ENVIRON "PATH=A:\" 


If your work subdirectory were john, you would be able to get DEBUG from 
the root. 


A new parameter may be added: 


ENVIRON "COMSPEC=A: \COMMAND.COM" 


The environment string table now contains 

PATH=A: \; COMSPEC=A: \COMMAND . COM 

The path may be changed to a new value: 

ENVIRON "PATH=A: \SALES; A: \ACCOUNTING" 


The path parameter may be appended by using the ENVIRON$ function with 
the ENVIRON statement: 


ENVIRON "PATH="+ENVIRONS ("PATH") +";B: \SAMPLES" 
Finally, delete the parameter COMSPEC: 

ENVIRON "COMSPEC=;" 

The environment string table now contains 


PATH=A: \SALES;A: \ACCOUNTING; B: \SAMPLES 
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ENVIRONS Function 


Purpose: 


To allow the user to retrieve the specified environment string from the 
environment table. 


Syntax: 


v$=ENVIRON$(parmid) 
v$=ENVIRONS$(nthparm) 


Comments: 


parmid is a valid string expression containing the parameter to search for. 
nthparm is an integer expression in the range of 1 to 255. 


If a string argument is used, ENVIRON$ returns a string containing the text 
following parmid= from the environment string table. 


If parmid is not found, then a null string is returned. 


If a numeric argument is used, ENVIRONS returns a string containing the nth 
parameter from the environment string table. 


If there is no nth parameter, then a null string is returned. 
The ENVIRONS$ function distinguishes between upper- and lowercase. 


Examples: 


The following lines: 


ENVIRON "PATH=A: \SALES;A: \ACOUNTING;B:\MKT:" ‘Create 
entry PRINT ENVIRONS ("PATH") ‘Print entry 


will print the following string: 
A: \SALES; A: \ACCOUNTING; B: \MKT 
The following line will print the first string in the environment: 


PRINT ENVIRONS (1) 
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The following program saves the environment string table in an array so that it 
can be modified for a child process. After the child process completes, the 
environment is restored. 


10 
20 
30 
40 
50 
60 
70 
72 
73 
74 
75 
90 
100 


1000 
1002 
1003 
1004 
1005 
1010 
1020 
1030 


DIM ENVTBIL$ (10) " 

NPARMS= 1 

WHILE LEN (ENVIRONS (NPARMS)) #0 
ENVTBL$ (NPARMS)= ENVIRONS (NPARMS) 
NPARMS= NPARMS + 1 

WEND 

NPARMS= NPARMS-1 

WHILE LEN (ENVIRONS (1) ) #0 

A$=MID$ (ENVIRONS (1),1,INSTR (ENVIRONS (1),"=")) 
ENVIRON AS+";" 

WEND 

ENVIRON "MYCHILDPARM1=SORT BY NAME" 
ENVIRON "MYCHILDPARM2=LIST BY NAME" 


SHELL "MYCHILD"’RUNS "MYCHILD.EXE" 

WHILE LEN (ENVIRONS (1) ) #0 

AS=MIDS (ENVIRONS (1),1, INSTR(ENVIRONS (1),"=")) 
ENVIRON AS+";" 

WEND 

FOR I=1 TO NPARMS 

ENVIRON ENVTBLS (I) 

NEXT I 


The DIM statement in line 10 assumes no more than 10 parameters will be 
accessed, 


In line 20, the initial number of parameters is established as 1. 


In lines 30 through 70, a series of statements are used to adjust and correct the 
parameter numbers. 


Line 71 deletes the present environment. 
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Lines 72 through 80 create a new environment. Line 74 deletes the string. 
Lines 80 through 100 store the new environment. 


Lines 1000 through 1030 repeat the procedure by deleting the present 
environment and restore the parameters established in the first part of the 


program. 
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EOF Function 


Purpose: 


To return -1 (true) when the end of a sequential or a communications file has 
been reached, or to return 0 if end of file (EOF) has not been found. 


Syntax: 


v=KOF(ftle number) 


Comments: 


If a GET is done past the end of the file, EOF returns -1. This may be used to 
find the size of a file using a binary search or other algorithm. With 
communications files, a -1 indicates that the buffer is empty. _ 


Use EOF to test for end of file while inputting to avoid “Input Past End" errors. 


Examples: 


10 OPEN "I",1,"DATA" 
20 C=0 

30 IF EOF (1) THEN 100 
40 INPUT#1,M(C) 

50 C=C+1:GOTO 30 

100 END 

RUN 


The file named DATA is read into the M array until the end of the file is 
reached, then the program branches to line 100. 
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ERASE Statement 
Purpose: 

To eliminate arrays from a program. 
Syntax: 

ERASE list of array variables 


Comments: 


Arrays may be redimensioned after they are erased, or the memory space 
previously allocated to the array may be used for other purposes. 


If an attempt is made to redimension an array without first erasing it, an error 
occurs. 


Examples: 


200 DIM B (250) 


450 ERASE A,B 
460 DIM B(3,4) 


Arrays A and B are eliminated from the program. The B array is redimensioned 
to a 3-column by 4-row array (12 elements), all of which are set to a zero value. 
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ERDEV and ERDEV$ Variables 


Purpose: 


To return the actual value (ERDEV) of a device error, and the name of the 
device (ERDEV$) causing the error. 


Syntax: 


ERDEV 
ERDEV$ 


Comments: 


ERDEYV will contain the error code from interrupt 24H in the lower 8 bits. Bits 
8 to 15 from the attribute word in the Device Header Block are mapped directly 
into the upper 8 bits. 


ERDEVS$ will contain the 8-byte character device name if the error was on a 
character device. It will contain the 2 byte block device name (A:, B:, etc.) if 
the device was not a character device. 


Examples: 


Installed device driver Ipt2: caused a "Printer out of paper” error via INT 24H. 


ERDEV contains the error number 9 in the lower 8 bits, while the upper 8 bits 
contain the upper byte of the Device Header word attributes. 


ERDEVS contains "LPT2: ae 
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ERR and ERL Variables 


Purpose: 


To return the error code (ERR) and line number (ERL) associated with an error. 


Syntax: 


v=ERR 
v=ERL 


Comments: 


The variable ERR contains the error code for the last occurrence of an error. 
All the error codes and their definitions are listed in Appendix A of the GW- 
BASIC User's Guide. 

The variable ERL contains the line number of the line in which the error was 
detected. 

The ERR and ERL Variables are usually used in IF-THEN, or ON 
ERROR...GOTO, or GOSUB statements to direct program flow in error 
trapping. 

If the statement that caused the error was a direct mode statement, ERL will 
contain 65535. To test if an error occurred in a direct mode statement, use a 
line of the following form: 


IF 65535=ERL THEN ... 
Otherwise, use the following: 


10 IF ERR=error code THEN...GOSUB 4000 
20 IF ERL=line number THEN...GOSUB 4010 
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Note If the line number is not on the right side of the relational operator, it 
cannot be renumbered by RENUM. 


Because ERL and ERR are reserved variables, neither may appear to the left of 
the equal sign in a LET (assignment) statement. 
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ERROR Statement 


Purpose: 


To simulate the occurrence of an error, or to allow the user to define error 
codes. 


Syntax: 


ERROR integer expression 


Comments: 


The value of integer expression must be greater than 0 and less than 255. 

If the value of integer expression equals an error code already in use by 
cwaasic, the ERROR statement simulates the occurrence of that error, and the 
corresponding error message is printed. 

A user-defined crror code must use a value greater than any used by the 
GwBasic error codes. There are 76 Gw-BASIc error codes at present. It is 


preferable to use a code number high enough to remain valid when more error 
codes are added to Gw-BASIC. 


User-defined error codes may be used in an error-trapping routine. 


If an ERROR statement specifies a code for which no error message has been 
defined, Gw-Basic responds with the message "Unprintable Error”. 


Execution of an ERROR statement for which there is no error-trapping routine 
causes an error message to be printed and execution to halt. 


For a complete list of the error codes and messages already defined in GW-BASIC, 
refer to Appendix A in the GW-BASIC User's Guide. 


Examples: 


The following examples simulate error 15 (the code for "String too long"): 


LIST 
10 S=10 
20 T=5 
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30 ERROR S+T 

40 END 

Ok 

RUN 

String too long in 30 


Or, in direct mode: 


Ok 

ERROR 15 (you type this line) 

String too long (cw-BAsiC types this line) 
Ok 


The following example includes a user-defined error code message. 


110 ON ERROR GOTO 400 
120 INPUT "WHAT IS YOUR BET";B 
130 IF B>5000 THEN ERROR 210 


400 IF ERR=210 THEN PRINT "HOUSE LIMIT IS $5000" 
410 IF ERL=130 THEN RESUME 120 
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EXP Function 


Purpose: 
To return e (the base of natural logarithms) to the power of x. 


Syntax: 


EXP(x) 


Comments: 


x must be less than 88.02969. 

If EXP overflows, the "Overflow" error message appears; machine infinity with 
the appropriate sign is supplied as the result, and execution continues. 

EXP(x) is calculated in single precision, unless the /d switch is used when cw- 
BASIC is executed. 


Examples: 


10 X = 5 
20 PRINT EXP (X-1) 
RUN 

54.59815 
Ok 


Prints the value of e to the 4th power. 
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EXTERR Function 


Purpose: 


To return extended error information. 


Syntax: 


EXTERR(n) 


Comments: 


EXTERR returns "extended" error information provided by versions of DOS 
3.0 and greater. For versions of DOS earlier than 3.0, EXTERR always returns 
zero. The single integer argument must be in the range 0-3 as follows: 


Value of n Return Value 

0 Extended error code 

1 Extended error class 

2 Extended error suggested action 
3 Extended error locus 


The values returned are not defined by cw-nasic, but by DOS. Refer to the MS- 
DOS Programmer's Reference (version 3.0 or later) for a description of the 
values returned by the pos extended error function. 


The extended error code is actually retrieved and saved by cw-sasic each time 
appropriate DOS functions are performed. Thus when an EXTERR function 
call is made, these saved values are returned. 
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FIELD Statement 


Purpose: 


To allocate space for variables in a random file buffer. 


Syntax: 


FIELD [#] filenwm, width AS stringvar [,width AS stringvar]... 


Comments: 


filenum is the number under which the file was opened. 

width is the number of characters to be allocated to the string variable. 
string variable is a string variable which will be used for random file access. 
A FIELD statement must have been executed before you can 


e get data out of a random buffer after a GET statement 
e enter data before a PUT statement 


For example, the following line allocates the first 20 positions (bytes) in the 
random file buffer to the string variable N$, the next 10 positions to ID$, and 
the next 40 positions to ADD$: 


FIELD 1, 20 AS NS, 10 AS IDS, 40 AS ADD$ 


FIELD only allocates space, it does not place any data in the random file 
buffer. 

The total number of bytes allocated in a FIELD statement must not exceed the 
record length specified when the file was opened. Otherwise, a "Field 
overflow" error occurs (the default record length is 128). 

Any number of FIELD statements may be executed for the same file, and all 
FIELD statements executed are in effect at the same time. 
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Note Do not use a fielded variable name in an INPUT or LET statement. Once 
a variable name is fielded, it points to the correct place in the random file 
buffer. If a subsequent INPUT or LET statement with that variable name is 
executed, the variable’s pointer is moved to string space (see LSET/RSET and 
GET statements). 
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FILES Command 


Purpose: 


To print the names of the files residing on the specified drive. 


Syntax: 


FILES [pathname] 


Comments: 


If pathname is omitted, the command lists ail files in the current directory of 
the selected drive. pathname may contain question marks (?) to match any 
character in the filename or extension. An asterisk (*) as the first character of 
the filename or extension will match any file or any extension. 

This syntax also displays the name of the directory and the number of bytes in 
the file. When a tree-structured directory is used, two special symbols also 
appear. 


Subdirectories are denoted by <DIR> following the directory name. 


Examples: 


FILES 

FILES "*.BAS" 
FILES "B:*.*" 
FILES "TEST?.BAS" 


FILES now allows pathnames. The directory for the specified path is displayed. 
If an explicit path is not given, the current directory is assumed. 


FILES "ACCTS\" 


Lists all files in the directory named accts that are on the diskette in Drive B: 
and have the extension of .pay. 


FILES "B:ACCTS\*.PAY" 


Lists all files in the directory named accts that are on the diskette in Drive B: 
and have the extension of .PAY. 
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FIX Function 
Purpose: 


To truncate x to a whole number. 


Syntax: 


FIX(x) 


Comments: 


FIX does not round off numbers, it simply eliminates the decimal point and all 
characters to the right of the decimal point. 


FIX(x) is equivalent to SGN(x)*INT(ABS(x)). The major difference between 
FIX and INT is that FIX does not retum the next lower number for negative x. 


FIX is useful in modulus arithmetic. 


Examples: 


PRINT FIX (58.75) 


58 

Ok 

PRINT FIX (-58.75) 
-58 


Ok 
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FOR and NEXT Statements 


Purpose: 


To execute a series of instructions a specified number of times in a loop. 


Syntax: 


FOR variable=x TO y [STEP z] 


NEXT [variable][,variable...] 


Comments: 


variable is used as a counter. 

x,y, and z are numeric expressions. 

STEP z specifies the counter increment for each loop. 

The first numeric expression (x) is the initial value of the counter. The second 
numeric expression (y) is the final value of the counter. 


Program lines following the FOR statement are executed until the NEXT 
statement is encountered. Then, the counter is incremented by the amount 
specified by STEP. 

If STEP is not specified, the increment is assumed to be 1. 


A check is performed to see if the value of the counter is now greater than the 
final value (y). If it is not greater, Gw-Basic branches back to the statement after 
the FOR statement, and the process is repeated. If it is greater, execution 
continues with the statement following the NEXT statement. This is a FOR- 
NEXT loop. 


The body of the loop is skipped if the initial value of the loop times the sign of 
the step exceeds the final value times the sign of the step. 
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If STEP is negative, the final value of the counter is set to be less than the 
initial value. The counter is decremented each time through the loop, and the 
loop is executed until the counter is less than the final value. 


Nested Loops 


FOR-NEXT loops may be nested; that is, a FOR-NEXT loop may be placed 
within the context of another FOR-NEXT loop. When loops are nested, each 
loop must have a unique variable name as its counter. 

The NEXT statement for the inside loop must appear before that for the outside 
loop. 

If nested loops have the same end point, a single NEXT statement may be used 
for all of them. 

The variable(s) in the NEXT statement may be omitted, in which case the 
NEXT statement will match the most recent FOR statement. 

If a NEXT statement is encountered before its corresponding FOR statement, a 
"NEXT without FOR" error message is issued and execution is terminated. 


Examples: 


The following example prints integer values of the variable I% from 1 to 10 in 
steps of z. For fastest execution, I is declared as an integer by the % sign. 


10 K=10 
20 FOR I%=1 TO K STEP 2 
30 PRINT I> 


60 NEXT 
RUN 


Fon nwr 
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In the following example, the loop does not execute because the initial value of 
the loop exceeds the final value. Nothing is printed by this example. 


10 R=0 

20 FOR S=1 TO R 
30 PRINT S 

40 NEXT S 


In the next example, the loop executes 10 times. The final value for the loop 
variable is always set before the initial value is set. 


10 S=5 
20 FOR S=1 TO S+5 
30 PRINT S; 
40 NEXT 
RUN 
12345678 9 10 
Ok 
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FRE Function 


Purpose: 
To return the number of available bytes in allocated string memory. 


Syntax: 


FREQ$) 
FRE(x) 


Comments: 


Arguments (x$) and (x) are dummy arguments. 

Before FRE (x$) returns the amount of space available in allocated string 
memory, GW-BASIC initiates a "garbage collection” activity. Data in string 
memory space is collected and reorganized, and unused portions of fragmented 
strings are discarded to make room for new input. 


If FRE is not used, Gw-BAsic initiates an automatic garbage collection activity 
when all string memory space is used up. Gw-Basic will not initiate garbage 
collection until all free memory has been used. Garbage collection may take 1 
to 1.5 minutes. 


FRE("") or any string forces a garbage collection before returning the number 
of free bytes. Therefore, using FRE("") periodically will result in shorter delays 
for each garbage collection. 


It should be noted that the crRL-BREAK function cannot be used during this 
housecleaning process. 


Examples: 


PRINT FRE (0) 
14542 
Ok 


Your computer may return a different value. 
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GET Statement (Files) 


Purpose: 


To read a record from a random disk file into a random buffer. 


Syntax: 


GET [#]file number[,record number] 


Comments: 


file number is the number under which the file was opened. 
record number is the number of the record, within the range of 1 to 16,777,215. 


If record number is omitted, the next record (after the last GET) is read into the 
buffer. 


After a GET statement, INPUT# and LINE INPUT# may be used to read 
characters from the random file buffer. 


GET may also be used for communications files. record number is the number 
of bytes to be read from the communications buffer. record number cannot 
exceed the buffer length set in the OPEN COM(n) statement. 


Examples: 


The following example opens the vendor file for random access, defines the 
fields, reads a record, then displays it: 


10 OPEN "R",1,"A:VENDOR.FIL" 

20 FIELD 1,30 AS VENDNAMESS,20 AS ADDR$,15 AS 
CITYS 

30 GET 1 

40 PRINT VENDNAMESS,ADDRS,CITY$ 

50 CLOSE 1 


This example opens the file vendor fil for random access, with fields defined in 
line 20. In line 30, the GET statement reads a record into the file buffer. Line 
40 displays the information from the record just read. Line 50 closes the file. 
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GET Statement (Graphics) 
Purpose: 


To transfer graphics images from the screen. 


Syntax: 


GET (x1,y1)-(x2,y2),array name 


Comments: 


The PUT and GET statements are used to transfer graphics images to and from 
the screen. PUT and GET make animation and high-speed object motion 
possible in either graphics mode. 

The GET statement transfers the screen image bounded by the rectangle 
described by the specified points into the array. The rectangle is defined the 
same way as the rectangle drawn by the LINE statement using the ,B option. 
The array is used simply as a place to hold the image, and can be of any type 
except string. It must be dimensioned large enough to hold the entire image. 
The contents of the array after a GET will be meaningless when interpreted 
directly (unless the array is of the type integer, as shown below). 


The storage format in the array is as follows: 

èe 2bytes given x dimension in bits 

e 2 bytes given y dimension in bits 

e the array data itself 

The data for each row of pixels is left-justified on a byte boundary. If less than 


a multiple of eight bits is stored, the rest of the byte will be filled out with 
zeros. The required array size in bytes is as follows: 


4+INT ((x*bitsperpixel+7)/8)*y 
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See the SCREEN statement for bitsperpixel values for different screen modes. 
The bytes-per-element of an array are as follows: 


e 2 for integer 
e 4 for single-precision 
e 8 for double-precision 


The number of bytes required to get a 10 by 12 image into an integer array is 
4+INT((10*2+7)/8)*12, or 40 bytes. An integer array with at least 20 elements 
is necessary. 


If OPTION BASE equals zero, an integer array can be used to examine the x 
and y dimensions and the data. The x dimension is in element 0 of the array, 
and the y dimension is in element 1. Integers are stored low byte first, then high 
byte, but data is transferred high byte first (left-most), then low byte. 


It is possible to get an image in one mode and put it in another, although the 
effect may be quite strange because of the way points are represented in each 
mode. 


Examples: 


10 CLS: SCREEN 1 

20 PSET (130,120) 

30 DRAW "U25;E7;R20;D32;L6;U12;1L14" 
40 DRAW "D12;L6":PSET (137,102) 

50 DRAW "U4;E4;R8;D8;L12" 

60 PSET (137, 88) 

70 DRAW "E4;R20;D32;G4":PAINT (139, 87) 
80 DIM A(500) 

90 GET (125,130)-(170,80),A 

100 FOR I=1 TO 1000:NEXT I 

110 PUT (20,20),A,PSET 

120 FOR I=1 TO 1000:NEXT I 

130 GET (125,130)-(170,80),A 

140 FOR I=1 TO 1000:NEXT I 

150 PUT (220,130) ,A,PRESET 
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GOSUB...RETURN Statement 


Purpose: 


To branch to, and return from, a subroutine. 


Syntax: 


GOSUB line number 


RETURN [line number] 


Comments: 


line number is the first line number of the subroutine. 


A subroutine may be called any number of times in a program, and a subroutine 
may be called from within another subroutine. Such nesting of subroutines is 
limited only by available memory. 


A RETURN statement in a subroutine causes Gw-BAsiIc to return to the statement 
following the most recent GOSUB statement. A subroutine can contain more 
than one RETURN statement, should logic dictate a RETURN at different 
points in the subroutine. 


Subroutines can appear anywhere in the program, but must be readily 
distinguishable from the main program. 


To prevent inadvertent entry, precede the subroutine by a STOP, END, or 
GOTO statement to direct program control around the subroutine. 


Examples: 


10 GOSUB 40 

20 PRINT "BACK FROM SUBROUTINE" 
30 END 

40 PRINT "SUBROUTINE"; 

50 PRINT " IN"; 

60 PRINT " PROGRESS" 

70 RETURN 
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RUN 

SUBROUTINE IN PROGRESS 
BACK FROM SUBROUTINE 
Ok 


The END statement in line 30 prevents re-execution of the subroutine. 
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GOTO Statement 


Purpose: 


To branch unconditionally out of the normal program sequence to a specified 
line number. 


Syntax: 


GOTO line number 


Comments: 


line number is any valid line number within the program. 


If line number is an executable statement, that statement and those following 
are cxecuted. If it is a nonexecutable statement, execution proceeds at the first 
executable statement encountered after line number. 


Examples: 


10 READ R 

20 PRINT "R =";R; 
30 A = 3.14*R*2 

40 PRINT "AREA =";A 
50 GOTO 10 

60 DATA 5,7,12 

RUN 

R = 5 AREA = 78.5 

R = 7 AREA = 153.86 
R = 12 AREA = 452.16 
Out of data in 10 
Ok 


The “out of data” advisory is generated when the program attempts to read a 
fourth DATA statement (which does not exist) in line 60. 
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HEX$ Function 


Purpose: 


To return a string which represents the hexadecimal value of the numeric 
argument. 


Syntax: 


v$=HEX$(x) 


Comments: 


HEX$ converts decimal values within the range of -32768 to +65535 into a 
hexadecimal string expression within the range of 0 to FFFF. 


Hexadecimal numbers are numbers to the base 16, rather than base 10 (decimal 
numbers). Appendixes C and G in the GW-BASIC User's Guide contain more 
information on hexadecimals and their equivalents. 


x is rounded to an integer before HEX$(x) is evaluated. See the OCT$ function 
for octal conversions. 


If x is negative, 2’s (binary) complement form is used. 


Examples: 


10 CLS: INPUT “INPUT DECIMAL NUMBER"; X 
20 AS=HEXS (X) 
30 PRINT X "DECIMAL IS "A$" HEXADECIMAL" 
RUN 
INPUT DECIMAL NUMBER? 32 

32 DECIMAL IS 20 HEXADECIMAL 
Ok 
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IF Statement 
Purpose: 


To make a decision regarding program flow based on the result returned by an 
expression. 


Syntax: 


IF expression[,] THEN statement(s)[,][ELSE statement(s)] 
IF expression[,] GOTO line number[[,] ELSE statement(s)] 


Comments: 


If the result of expression is nonzero (logical true), the THEN or GOTO line 
number is executed. 

If the result of expression is zero (false), the THEN or GOTO line number is 
ignored and the ELSE line number, if present, is executed. Otherwise, 
execution continues with the next executable statement. A comma is allowed 
before THEN and ELSE. 

THEN and ELSE may be followed by either a line number for branching, or 
one or more statements to be executed. 

GOTO is always followed by a line number. 

If the statement does not contain the same number of ELSE’s and THEN’s line 
number, each ELSE is matched with the closest unmatched THEN. For 
example: 


IF A=B THEN IF B=C THEN PRINT “A=C" ELSE PRINT "A < > 
Cc" 


will not print "A < > C" when A <> B. 


If an IF... THEN statement is followed by a line number in the direct mode, an 
"Undefined line number” error results, unless a statement with the specified 
line number was previously entered in the indirect mode. 


Because IF ..THEN...ELSE is all one statement, the ELSE clause cannot be on 
a separate line. It must be all on one line. 
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Nesting of IF Statements 


IF... THEN...ELSE statements may be nested. Nesting is limited only by the 
length of the line. For example, the following is a legal statement: 


100 IF X > Y THEN PRINT "GREATER" ELSE IF Y > X THEN& 
110 PRINT "LESS THAN" 
200 ELSE PRINT "EQUAL" 


Testing Equality 


When using IF to test equality for a value that is the result of a floating-point 
computation, remember that the internal representation of the value may not be 
exact. Therefore, test against the range over which the accuracy of the value 
may vary. 

For example, to test a computed variable A against the value 1.0, use the 
following statement: 

IF ABS (A-1.0)<1.0E-6 THEN ... 


This test returns true if the value of A is 1.0 with a relative error of less than 
1.0E-6. 


Examples: 


The following statement gets record number N, if N is not zero. 
200 IF N THEN GET#1,N 


In the following example, a test determines if N is greater than 10 and less than 
20. If N is within this range, DB is calculated and execution branches to line 
300. If N is not within this range, execution continues with line 110. 


100 IF(N<20) and (N>10) THEN DB=1979-1:GOTO 300 
110 PRINT "OUT OF RANGE" 


The next statement causes printed output to go either to the terminal or the line 
printer, depending on the value of a variable (OFLAG). If IOFLAG is zero, 
output goes to the line printer; otherwise, output goes to the terminal. 


210 IF IOFLAG THEN PRINT A$ ELSE LPRINT A$ 
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INKEY$ Variable 


Purpose: 


To return one character read from the keyboard. 


Syntax: 


v$=INKEY$ 


Comments: 


If no character is pending in the keyboard buffer, a null string (length zero) is 
returned. 


If several characters are pending, only the first is returned. The string will be 
one or two characters in length. 


Two character strings are used to return the extended codes described in 
Appendix C of the GW-BASIC User's Guide. The first character of a two 
character code is zero. 


No characters are displayed on the screen, and all characters except the 
following are passed to the program: 


CTRL- BREAK 
CTRL-NUM-LOCK 
CTRL-ALT-DEL 
CTRL-PRTSC 
PRTSC 


Examples: 


10 CLS: PRINT"PRESS RETURN 

20 TIMELIMIT% = 1000 

30 GOSUB 1010 

40 IF TIMEOUT% THEN PRINT "TOO LONG" ELSE PRINT "GOOD 
SHOW" 

50 PRINT RESPONSES 

60 END 
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1000 REM TIMED INPUT SUBROUTINE 
1010 RESPONSES=""" 

1020 FOR N%=1 TO TIMELIMIT% 

1030 AS=INKEYS$:IF LEN (A$)=0 THEN 1060 
1040 IF ASC(A$)=13 THEN TIMEOUT%=0: RETURN 
1050 RESPONSES=RESPONSES+A$ 

1060 NEXT N% 

1070 TIMEOUT$=1 : RETURN 


When this program is executed, and if the RETURN key is pressed before 1000 
loops are completed, then "GOOD SHOW" is printed on the screen. Otherwise, 
"TOO LONG" is printed. 


Since an INKEY$ statement scans the keyboard only once, place INKEY$ 
statements within loops to provide adequate response times for the operator. 


INP Function 91 





INP Function 
Purpose: 


To return the byte read from machine port n. 


Syntax: 


INP(n) 


Comments: 


n represents a valid machine port number within the range of 0 to 65535. 


The INP function is one way in which a peripheral device may communicate 
with a GW-BASIC program. 


INP is the complementary function to the OUT statement. 


Examples: 


100 A=INP (56) 


Upon execution, variable A contains the value present on port 56. The number 
returned will be within the range of 0 to 255, decimal. 
The assembly language equivalent to this statement is 


MOV DX, 56 
IN AL,DX 
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INPUT Statement 


Purpose: 


To prepare the program for input from the terminal during program execution. 


Syntax: 


INPUT([;][prompt string;] list of variables 
INPUT[;][prompt string,] list of variables 


Comments: 


prompt string is a request for data to be supplied during program execution. 
list of variables contains the variable(s) that stores the data in the prompt string. 


Each data item in the prompt string must be surrounded by double quotation 
marks, followed by a semicolon or comma and the name of the variable to 
which it will be assigned. If more than one variable is given, data items must 
be separated by commas. 

The data entered is assigned to the variable list. The number of data items 
supplied must be the same as the number of variables in the list. 

The variable names in the list may be numeric or string variable names 


(including subscripted variables). The type of each data item input must agree 
with the type specified by the variable name. 


Too many or too few data items, or the wrong type of values (for example, 
numeric instead of string), causes the message "?Redo from start" to be printed. 
No assignment of input values is made until an acceptable response is given. 


A comma may be used instead of a semicolon after prompt string to suppress 
the question mark. For example, the following line prints the prompt with no 
question mark: 


INPUT "ENTER BIRTHDATE", BS 
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If the prompt string is preceded by a semicolon, the RETURN key pressed by 
the operator is suppressed. During program execution, data on that line is 
displayed, and data from the next PRINT statement is added to the line. 


When an INPUT statement is encountered during program execution, the 
program halts, the prompt string is displayed, and the operator types in the 
requested data. Strings that input to an INPUT statement need not be 
surrounded by quotation marks unless they contain commas or leading or 
trailing blanks. 


When the operator presses the RETURN key, program execution continues. 


INPUT and LINE INPUT statements have built-in PRINT statements. When an 
INPUT statement with a quoted string is encountered during program 
execution, the quoted string is printed automatically (see the PRINT statement). 
The principal difference between the INPUT and LINE INPUT statements is 
that LINE INPUT accepts special characters (such as commas) within a string, 
without requiring double quotation marks, while the INPUT statement requires 
double quotation marks. 


Example 1: 


To find the square of a number: 


10 INPUT X 

20 PRINT X "SQUARED IS" X^2 

30 END 

RUN 

? 

The operator types a number (5) in response to the question mark. 


5 SQUARED IS 25 
Ok 


Example 2: 


To find the area of a circle when the radius is known: 


10 PI=3.14 
20 INPUT "WHAT IS THE RADIUS";R 
30 A=PI*R%2 
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40 PRINT "THE AREA OF THE CIRCLE IS";A 
50 PRINT 

60 GOTO 20 

RUN 

WHAT IS THE RADIUS? 7.4 

THE AREA OF THE CIRCLE IS 171.9464 


Note that line 20 in the above example makes use of the built-in PRINT 
statement contained within INPUT. 
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INPUT# Statement 


Purpose: 


To read data items from a sequential file and assign them to program variables. 


Syntax: 


INPUT# file number, variable list 


Comments: 


file number is the number used when the file was opened for input. 
variable list contains the variable names to be assigned to the items in the file. 


The data items in the file appear just as they would if data were being typed on 
the keyboard in response to an INPUT statement. 


The variable type must match the type specified by the variable name. 
With INPUT#, no question mark is printed, as it is with INPUT. 


Numeric Values 


For numeric values, leading spaces and line feeds are ignored. The first 
character encountered (not a space or line feed) is assumed to be the start of a 
number. The number terminates on a space, carriage retum, line feed, or 
comma. 


Strings 


If Gw-Basic is scanning the sequential data file for a string, leading spaces and 
line feeds are ignored. 


If the first character is a double quotation mark ("), the string will consist of all 
characters read between the first double quotation mark and the second. A 
quoted string may not contain a double quotation mark as a character. The 
second double quotation mark always terminates the string. 
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If the first character of the string is not a double quotation mark, the string 
terminates on a comma, Carriage return, line feed, or after 255 characters have 
been read. 

If end of the file is reached when a numeric or string item is being INPUT, the 
item is terminated. 


INPUT# can also be used with random files. 
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INPUT$ Function 


Purpose: 


To return a string of x characters read from the keyboard, or from file number. 


Syntax: 


INPUT$(x[,[#] fle number)] 


Comments: 


If the keyboard is used for input, no characters will appear on the screen. All 
control characters (except CTRL-BREAK) are passed through. cTRL-BREAK interrupts 
the execution of the INPUTS function. 


The INPUTS function is preferred over INPUT and LINE INPUT statements 
for reading communications files, because all ascu characters may be 
significant in communications. INPUT is the least desirable because input stops 
when a comma or carriage return is seen. LINE INPUT terminates when a 
carriage return is seen. 


INPUTS allows all characters read to be assigned to a string. INPUT$ will 
return x characters from the file number or keyboard. 


For more information about communications, refer to Appendix F in the GW- 
BASIC User's Guide. 


Example 1: 


The following example lists the contents of a sequential file in hexadecimal. 


10 OPEN"I",1, "DATA" 

20 IF EOF(1) THEN 50 

30 PRINT HEXS (ASC (INPUTS (1, #1))); 
40 GOTO 20 

50 PRINT 

60 END 
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Example 2: 


In the following program, the program pauses, awaiting a keyboard entry of 
either P or S. Line 130 continues to loop back to line 100 if the input is other 
than P or S. 


100 PRINT "TYPE P TO PROCEED OR S TO STOP" 
110 X$=INPUTS (1) 

120 IF X$="P" THEN 500 

130 IF X$="S" THEN 700 ELSE 100 
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INSTR Function 


Purpose: 


To search for the first occurrence of string y$ in x$, and return the position at 
which the string is found. 


Syntax: 


INSTR ([7,]x$,y$) 


Comments: 


Optional offset n sets the position for starting the search. The default value for 
nisl. 


If n equals zero, the error message "Illegal argument in line number" is 
returned. 


n must be within the range of 1 to 255. If n is out of this range, an "Illegal 
Function Call" error is returned. 


INSTR returns 0 if: 


e n>LEN(x$) 
èe x$is null 
e — y$ cannot be found 


If y$ is null, INSTR returns n. 
x$ and y$ may be string variables, string expressions, or string literals. 


Examples: 


10 X$="ABCDEBXYZ" 


20 YS="B" 
30 PRINT INSTR(X$,YS$) ;INSTR(4,X$, YS) 
RUN 

2 6 


Ok 
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The interpreter searches the string "ABCDFBXYZ" and finds the first 
occurrence of the character B at position 2 in the string. It then starts another 
search at position 4 (D) and finds the second match at position 6 (B). The last 


three characters are ignored, since all conditions set out in line 30 were 
satisfied. 
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INT Function 


Purpose: 


To truncate an expression to a whole number. 
Syntax: 
INT(x) 


Comments: 


Negative numbers return the next lowest number. 
The FIX and CINT functions also return integer values. 


Examples: 


PRINT INT (98.89) 


98 
Ok 
PRINT INT (~-12.11) 
=13 


Ok 
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IOCTL Statement 


Purpose: 


To allow Gw-sasic to send a “control data" string to a character device driver 
anytime after the driver has been opened. 


Syntax: 
IOCTL[#]file number,string 


Comments: 


file number is the file number open to the device driver. 
string is a valid string expression containing characters that control the device. 


IOCTL commands are generally 2 to 3 characters followed by an optional 
alphanumeric argument. An IOCTL string may be up to 255 bytes long, with 
commands within the string separated by semicolons. 


Examples: 


If a user had installed a driver to replace Ipt1, and that driver was able to set 
page length (the number of lines to print on a page before issuing a form feed), 
then the following lines would open the new Ipt1 driver and set the page length 
to 66 lines: 


OPEN "LPT1:" FOR OUTPUT AS #1 
IOCTL #1, "PL66" 
The following statements open Ipt1 with an initial page length of 56 lines: 


OPEN "\DEV\LPT1" FOR OUTPUT AS #1 
IOCTL #1, "PL56" 
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IOCTL$ Function 
Purpose: 


To allow cw-pasıc to read a “control data” string from an open character device 
driver. 


Syntax: 


IOCTLS$((#] file number) 


Comments: 


file number is the file number open to the device. 


The IOCTL$ function is generally used to get acknowledgement that an IOCTL 
statement succeeded or failed. It is also used to get device information, such as 
device width after an IOCTL statement requests it. 


Examples: 


10 ‘GW is a possible command 
20 ‘for get device width 

30 OPEN "\DEV\MYLPT" AS#1 

40 IOCTYL#1, "GW" 

50 ‘Save it in WID 

60 WID=VAL (IOCTLS (#1) ) 
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KEY Statement 


Purpose: 


To allow rapid entry of as many as 15 characters into a program with one 
keystroke by redefining Gw-sasic special function keys. 


Syntax: 


KEY key number,string expression 

KEY n,CHR$(hexcode)+CHR$(scan code) 
KEY ON 

KEY OFF 

KEY LIST 


Comments: 


key number is the number of the key to be redefined. key number may range 
from 1-20. 

string expression is the key assignment. Any valid string of 1 to 15 characters 
may be used. If a string is longer than 15 characters, only the first 15 will be 
assigned. Constants must be enclosed in double quotation marks. 


scan code is the variable defining the key you want to trap. Appendix H in the 
GW-BASIC User's Guide lists the scan codes for the keyboard keys. 


hexcode is the hexadecimal code assigned to the key shown below: 


Key Hexcode 
EXTENDED &H80 
CAPS LOCK &H40 
NUM LOCK &H20 
ALT &H08 
CTRL &H04 


SHIFT &H01, &H02, &H03 
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Hexcodes may be added together, such as &H03, which is both shift keys. 
Initially, the function keys are assigned the following special functions: 


F1 LIST F2 RUN<- 

F3 LOAD" F4 SAVE" 

F5  CONT<- F6 »"LPT1:"<- 

F7 TRON<- F8 TROFF<- 

F9 KEY F10 SCREEN 000<- 


Note <- (arrow) means that you do not have to press RETURN after each of these 
keys has been pressed. 


Any one or all of the 10 keys may be redefined. When the key is pressed, the 
data assigned to it will be input to the program. 


KEY key number, "string expression" 
Assigns the string expression to the specified key. 
KEY LIST 


List all 10 key values on the screen. All 15 characters of each value are 
displayed. 


KEY ON 


Displays the first six characters of the key values on the 25th line of the screen. 
When the display width is set at 40, five of the 10 keys are displayed. When the 
width is set at 80, all 10 are displayed. 


KEY OFF 


Erases the key display from the 25th line, making that line available for 
program use. KEY OFF does not disable the function keys. 
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If the value for key number is not within the range of 1 to 10, or 15 to 20, an 
"Illegal function call" error occurs. The previous KEY assignment is retained. 


Assigning a null string (length 0) disables the key as a function key. 


When a function key is redefined, the INKEY$S function returns one character 
of the assigned string per invocation. If the function key is disabled, INKEY$ 
returns a string of two characters: the first is binary zero; the second is the key 
scan code. 


Examples: 


10 KEY 1, "MENU"+CHRS (13) 

Displays a menu selected by the operator each time key 1 is pressed. 
1 KEY OFF 

Turns off the key display. 


10 DATA KEY1, KEY2,KEY3,KEY4,KEYS5S 
20 FOR N=1 TO 5:READ SOFTKEYSS (n) 
30 KEY N, SOFTKEYS$ (I) 

40 NEXT N 

50 KEY ON 


Displays new function keys on line 25 of the screen. 
20 KEY 1,"" 
Disables function key 1. 
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KEY(n) Statement 
Purpose: 


To initiate and terminate key capture in a Gw-BASIC program. 


Syntax: 


KEY(n) ON 
KEY(n) OFF 
KEY(n) STOP 


Comments: 


nis a number from 1 to 20 that indicates which key is to be captured. Keys are 
numbered as follows: 


Key Number Key 

1-10 Function keys Fi through F10 

11 CURSOR-UP 

12 CURSOR-LEFT 

13 CURSOR-RIGHT 

14 CURSOR-DOWN 

15-20 Keys defined in the following format (see KEY statement): 


KEY n,CHR$(hexcode)+CHR$(scan code) 


Execution of the KEY(n) ON statement is required to activate keystroke 
capture from the function keys or cursor control keys. When the KEY(n) ON 
statement is activated and enabled, cw-Basic checks each new statement to see if 
the specified key is pressed. If so, Gw-Basic performs a GOSUB to the line 
number specified in the ON KEY(n) statement. An ON KEY(n) statement must 
precede a KEY(n) statement. 


When KEY(n) OFF is executed, no key capture occurs and no keystrokes are 
retained. 
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If KEY(n) STOP is executed, no key capture occurs, but if a specified key is 
pressed, the keystroke is retained so that immediate keystroke capture occurs 
when a KEY(n) ON is executed. 


For further information on key trapping, see the ON KEY (n) statement. 
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KILL Command 


Purpose: 


To delete a file from a disk. 


Syntax: 


KILL filename 


Comments: 


filename can be a program file, sequential file, or random-access data file. 


KILL is used for all types of disk files, including program, random data, and 
sequential data files. 


Note You must specify the filename’s extension when using the KILL 
command. Remember that files saved in Gw-sasic are given the default 
extension .bas. 


If a KILL command is given for a file that is currently open, a "File already 
open” error occurs. 


Examples: 


The following command deletes the cw-sasic file data, and makes the space 
available for reallocation to another file: 


200 KILL "DATA1.BAS" 


The following command deletes the cw-nasic file raining from the subdirectory 
dogs: 


KILL "CATS\DOGS\RAINING.BAS" 
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LEFT$ Function 


Purpose: 


To return a string that comprises the leftmost n characters of x$ 


Syntax: 


LEFT$ x$,n) 


Comments: 


n must be within the range of 0 to 255. If n is greater than LEN(x$), the entire 
string (x$) will be returned. If n equals zero, the null string (length zero) is 
returned (see the MID$ and RIGHTS substring functions). 


Example: 


10 A$="BASIC" 

20 BS=LEFTS (AS,'3) 
30 PRINT BS 

RUN 

BAS 

Ok 


The leftmost three letters of the string "BASIC" are printed on the screen. 
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LEN Function 
Purpose: 


To return the number of characters in x$. 


Syntax: 


LEN(x$) 


Comments: 


Nonprinting characters and blanks are counted. 


Example: 


x$ is any string expression. 


10 X$="PORTLAND, OREGON" 
20 PRINT LEN (X$) 

16 

Ok 


Note that the comma and space are included in the character count of 16. 
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LET Statement 
Purpose: 


To assign the value of an expression to a variable. 


Syntax: 


[LET] variable=expression 


Comments: 


The word LET is optional; that is, the equal sign is sufficient when assigning an 
expression to a variable name. 


The LET statement is seldom used. It is included here to ensure compatibility 
with previous versions of BASIC that require it.PWhen using LET, remember 
that the type of the variable and the type of the expression must match. If they 
don’t, a "Type mismatch” error occurs. 


Example 1: 


The following example lets you have downward compatibility with an older 
system. If this downward compatibility is not required, use the second example, 
as it requires less memory. 


110 LET D=12 

120 LET E=12%2 
130 LET F=12%4 
140 LET SUM=D+tE+F 


Example 2: 


110 D=12 

120 E=12%2 
130 F=12%4 
140 SUM=D+E+F 
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LINE Statement 
Purpose: 


To draw lines and boxes on the screen. 


Syntax: 


LINE [(xJ,y/)]-(x2,y2) [,[attribute][,B[F]]L style] 


Comments: 


xl,yl and x2,y2 specify the end points of a line. 
Resolution mode is determined by the SCREEN statement. 


attribute specifies color or intensity of the displayed pixel (see the COLOR and 
PALETTE statements). 


B (box) draws a box with the points (x/,y/) and (x2,y2) at opposite comers. 
BF (filled box) draws a box (as ,B) and fills in the interior with points. 


Note If attribute is not specified, two commas must be used before B or BF. 


LINE supports the additional argument style. style is a 16-bit integer mask used 
when putting down pixels on the screen. This is called line-styling. 

Each time LINE stores a point on the screen, it uses the current circulating bit 
in style. If that bit is 0, no store will be done. If the bit is a 1, then a normal 
store is done. After each point, the next bit position in style is selected. 


Since a 0 bit in style does not clear out the old contents, you may wish to draw 
a background line before a styled line, in order to force a known background. 
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style is used for normal lines and boxes, but is illegal for filled boxes. 


If the BF parameter is used with the style parameter, a "Syntax" error will 
occur. 


When out-of-range values are given in the LINE statement, the coordinates that 
are out of range are not visible on the screen. This is called line-clipping. 


In the syntax shown here, the coordinate form STEP (x offset,y offset) is not 
shown. However, this form can be used wherever a coordinate is used. 


In a LINE statement, if the relative form is used on the second coordinate, it is 
relative to the first coordinate. 


After a LINE statement, the last referenced point is x2, y2. 
The simplest form of LINE is the following: 
LINE -(xz,yz) 


This draws a line from the last point referenced to the point (xz,yz) in the 
foreground color. 


Examples: 


LINE (0,100)- (639,100) 


Draws a horizontal line which divides the screen in half from top to bottom in 
SCREEN 2. 


LINE (160,0)- (160,199) 


Draws a vertical line which divides the screen in half from left to right in 
SCREEN 1; makes a one-quarter/three-quarter division in SCREEN 2. 


LINE (0,0)- (319,199) 


Draws a diagonal line from the top left to lower right corner of the screen in 
SCREEN 1, and from the upper left comer to the center bottom of the screen 
in SCREEN 2. 
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LINE (10,10)-(20,20),2 


Draws a line in color 2 if SCREEN 1 is previously specified (see the COLOR 
statement). 


10 CLS 
20 LINE - (RND*319,RND*199) ,RND*4 
30 GOTO 20 


Draw lines forever using random attributes. 


10 FOR X=0 TO 319 
20 LINE (X,0)-(X,199),X AND 1 
30 NEXT 


Draws an alternating pattern: line on, line off. 


10 CLS 
20 LINE — (RND*639,RND*199) ,RND*2, BF 
30 GOTO 20 


Draws lines all over the screen. 

LINE (0,0)-(100,175),,B 

Draws a square box in the upper left corner of the screen. 
LINE (0,0)-(100,175),,BF 

Draws the same box and fills it in. 

LINE (0,0)-(100,175),2,BF 

Draws the same filled box in magenta in SCREEN 1. 
LINE (0,0)-(100,350),,B 

Draws the same box if SCREEN 2 is specified. 


400 SCREEN 1 
410 LINE (160,100) -(160,199),,,&HCCCC 


Draws a vertical dotted line down the center of the screen in SCREEN 1. 
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220 SCREEN 2 
230 LINE (300,100) -(400,50),,B, &HAAAA 


Draws a rectangle with a dotted line in SCREEN 2. 
LINE (0,0)-(160,100) ,3,,&HFFOO 


Draws a dotted line from the upper left corner to the screen center. 
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LINE INPUT Statement 


Purpose: 


To input an entire line (up to 255 characters) from the keyboard into a string 
variable, ignoring delimiters. 


Syntax: 


LINE INPUT [;][prompt string;|string variable 


Comments: 


prompt string is a string literal, displayed on the screen, that allows user input 
during program execution. 

A question mark is not printed unless it is part of prompt string. 

string variable accepts all input from the end of the prompt to the carriage 
return. Trailing blanks are ignored. 

LINE INPUT is almost the same as the INPUT statement, except that it accepts 
special characters (such as commas) in operator input during program 
execution. 

If a line-feed/carriage return sequence (this order only) is encountered, both 
characters are input and echoed. Data input continues. 


If LINE INPUT is immediately followed by a semicolon, pressing the 
RETURN key will not move the cursor to the next line. 


A LINE INPUT may be escaped by typing cTRL-BREAK. GW-BASIC returns to 
command level and displays Ok. 


Typing CONT resumes execution at the LINE INPUT line. 
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Example: 


100 LINE INPUT A$ 


Program execution pauses at line 100, and all keyboard characters typed 
thereafter are input to string A$ until RETURN, CTRL-M, CTRL-C, OF CTRL-BREAK iS 
entered. 
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LINE INPUT# Statement 


Purpose: 


To read an entire line (up to 255 characters), without delimiters, from a 
sequential disk file to a string variable. 


Syntax: 


LINE INPUT# file number, string variable 


Comments: 


file number is the number under which the file was opened. 
string variable is the variable name to which the line will be assigned. 


LINE INPUT# reads all characters in the sequential file up to a carriage return. 
If a line feed/carriage return sequence (this order only) is encountered, it is 
input. 

LINE INPUT# is especially useful if each line of a data file has been broken 
into fields, or if a Basıc program saved in ascu mode is being read as data by 
another program. 


Examples: 


10 OPEN "0O",1,"INFO" 

20 LINE INPUT "CUSTOMER INFORMATION?";CS$ 
30 PRINT#1, C$ 

40 CLOSE 1 

50 OPEN "I",1,"INFO" 

60 LINE INPUT#1, C$ 

70 PRINT C$ 

80 CLOSE 1 

RUN 

CUSTOMER INFORMATION? 


If the operator enters 


LINDA JONES 234,4 MEMPHIS 
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then the program continues with the following: 


LINDA JONES 234,4 MEMPHIS 
Ok 
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LIST Command 


Purpose: 


To list all or part of a program to the screen, line printer, or file. 


Syntax: 


LIST [line nwnber][-line number)[ filename] 
LIST [line number-][ filename] 


Comments: 


linenumber is a valid line number within the range of 0 to 65529. 
If filename is omitted, the specified lines are listed to the screen. 


Use the hyphen to specify a line range. If the line range is omitted, the entire 
program is listed. linenumber- lists that line and all higher numbered lines. 
-linenumber lists lines from the beginning of the program through the specified 
line. 


The period (.) can replace either linenumber to indicate the current line. 
Any listing may be interrupted by pressing CTRL-BREAK. 


Examples: 


LIST 

Lists all lines in the program. 
LIST -20 

Lists lines 1 through 20. 
LIST 10-20 

Lists lines 10 through 20. 
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List 20- 


Lists lines 20 through the end of the program. 
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LLIST Command 


Purpose: 


To list all or part of the program currently in memory to the line printer. 


Syntax: 


LLIST [line number][-line number] 
LLIST [line nwnber-]} 


Comments: 


GW-BASIC always returns to command level after a LLIST is executed. The line 
range options for LLIST are the same as for LIST. 


Examples: 


See the examples in the LIST statement. 
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LOAD Command 


Purpose: 


To load a file from diskette into memory. 


Syntax: 


LOAD filename[,r] 


Comments: 


filename is the filename used when the file was saved. If the extension was 
omitted, .bas will be used. 


LOAD closes all open files and deletes all variables and program lines 
currently residing in memory before it loads the designated program. 


If the r option is used with LOAD, the program muns after it is loaded, and all 
open data files are kept open. 


LOAD with the r option lets you chain several programs (or segments of the 
same program). Information can be passed between the programs using the disk 
data files. 


Examples: 


LOAD "STRTRK",R 


Loads the file strirk.bas and runs it, retaining all open files and variables from a 
previous program intact. 
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LOC Function 
Purpose: 


To return the current position in the file. 


Syntax: 


LOC (ile number) 


Comments: 


file number is the file number used when the file was opened. 

When transmitting or receiving a file through a communication port, LOC 
returns the number of characters in the input buffer waiting to be read. The 
default size for the input buffer is 256 characters, but can be changed with the 
lc: option on the GW-BASIC command line. If there are more than 255 
characters in the buffer, LOC returns 255. Since a string is limited to 255 
characters, this practical limit alleviates the need to test for string size before 
reading data into it. If fewer than 255 characters remain in the buffer, then LOC 
returns the actual count. 

With random disk files, LOC returns the record number just read from, or 
written to, with a GET or PUT statement. 

With sequential files, LOC returns the number of 128-byte blocks read from, or 
written to, the file since it was opened. When the sequential file is opened for 
input, GW-BASIC initially reads the first sector of the file. In this case, the 
LOC function returns the character 1 before any input is allowed. 

If the file was opened but no disk input/output was performed, LOC returns a 
zero. 


Examples: 


200 IF LOC(1)>50 THEN STOP 


The program stops after 51 records are read or written. 
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LOCATE Statement 


Purpose: 


To move the cursor to the specified position on the active screen. Optional 
parameters cause the cursor to blink on and off, and define the start and stop 
raster lines for the cursor. A raster line is the vertical or horizontal distance 
between two adjacent, addressable points on your screen. 


Syntax: 


LOCATE [row][,[col][,[cursor][,[start] [,stop]}}]] 


Comments: 


row is the screen line number, a numeric expression within the range of 1 to 25. 


col is the screen column number, a numeric expression within the range of 1 to 
40, or 1 to 80, depending upon screen width. 


cursor is a boolean value indicating whether the cursor is visible; zero is off, 
nonzero is on. 

start is the cursor start scan line, a numeric expression within the range of 0 to 
31. 


stop is the cursor stop scan line, a numeric expression within the range of 0 to 
31. 


When the cursor is moved to the specified position, subsequent PRINT 
statements begin placing characters at this location. Optionally, the LOCATE 
statement may be used to start the cursor blinking on or off, or change the size 
of the blinking cursor. 


Any values entered outside of these ranges results in "Illegal function call” 
errors. Previous values are retained. 


As you set up the parameters for the LOCATE statement, you may find that 
you do not wish to change one or more of the existing specifications. To omit a 
parameter from this LOCATE statement, insert a comma for the parameter that 
is being skipped. If the omitted parameter(s) occurs at the end of the statement, 
you do not have to type the comma. 
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If the start scan line parameter is given and the stop scan line parameter is 
omitted, stop assumes the start value. 


Examples: 


10 LOCATE 1,1 
Moves cursor to the home position in the upper-left corner. 
20 LOCATE ,,1 


Makes the cursor visible. Its position remains unchanged. Notice that the first 
two parameters are not used. A comma has been inserted for each omitted 
parameter. 


30 LOCATE ,,,7 


Cursor position and visibility remain unchanged. Sets the cursor to appear at 
the bottom of the character starting and ending on scan line 7. 


40 LOCATE 5,1,1,0,7 


Moves the cursor to line 5, column 1, and turns the cursor on. The cursor 
covers an entire character cell, starting at scan line 0 and ending on scan line 7. 
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LOCK Statement 


Purpose: 


To restrict the access to all or part of a file that has been opened by another 
process. This is used in a multi-device environment, often referred to as a 
network or network environment. 


Syntax: 


LOCK [#]x [,[record number] [TO record number]] 


Comments: 


nis the number that was assigned to the file as it was originally numbered in 
the program. 


record number is the number of the individual record that is to be locked. Or, if 
a range of records are to be locked, record number designates the beginning 
and ending record of the specified range. 


The range of legal record numbers is 1 to 2 32 —1. The limit on record size is 
32767 bytes. 


The record range specified must be from lower to (the same or) higher record 
numbers. 


If a starting record number is not specified, the record number 1 is assumed. 


If an ending record number is not specified, then only the specified record is 
locked. 


The following are examples of legal LOCK statements: 


LOCK #n locks the entire file n 
LOCK #n, X locks record X only 
LOCK #n,TO Y locks records 1 through Y 
LOCK #n, X TO Y locks records X through Y 


With a random-access file, the entire opened file, or a range of records within 
an opened file, may be locked, thus denying access to those records to any 
other process which has also opened the file. 


With a sequential access file that has been opened for input or output, the entire 
file is locked, regardless of any record range specified. This is not considered 
an error. The specification of a range in the LOCK statement regarding the 
sequential file will simply be disregarded. 
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The LOCK statement should be executed on a file or record range within a file 
before attempting to read or write to that file. 


The locked file or record range should be unlocked before the file is closed. 
Failure to execute the UNLOCK statement can jeopardize future access to that 
file in a network environment. 


It is expected that the time in which files or regions within files are locked will 
be short, and thus the suggested usage of the LOCK statement is within short- 
term paired LOCK/UNLOCK statements. 


Examples: 


The following sequence demonstrates how the LOCK/UNLOCK statements 
should be used: 


LOCK #1, 1 TO 4 
LOCK #1, 5 TO 8 
UNLOCK #1, 1 TO 4 
UNLOCK #1, 5 TO 8 


The following example is illegal: 


LOCK #1, 1 TO 4 
LOCK #1, 5 TO 8 
UNLOCK #1, 1 TO 8 
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LOF Function 

Purpose: 

To return the length (number of bytes) allocated to the file. 
Syntax: 


LOF (file number) 


Comments: 


file number is the number of the file that the file was opened under. 


With communications files, LOF returns the amount of free space in the input 
buffers. 


Examples: 


The following sequence gets the last record of the random-access file file.big, 
and assumes that the file was created with a default record length of 128 bytes: 


10 OPEN "R",1,"FILE.BIG" 
20 GET #1,LOF(1)/128 
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LOG Function 


Purpose: 


To return the natural logarithm of x. 


Syntax: 
LOG(z) 


Comments: 


x must be a number greater than zero. 


LOG(x) is calculated in single precision, unless the /d switch is used when Gw- 
BASIC is executed. 


Examples: 


PRINT LOG (2) 
- 6931471 


PRINT LOG (1) 
0 
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LPOS Function 
Purpose: 


To return the current position of the lineprinter print head within the line printer 
buffer. 


Syntax: 


LPOS(@) 


Comments: 


LPOS does not necessarily give the physical position of the print head. 
x is a dummy argument. 


If the printer has less than the 132 characters-per-line capability, it may issue 
internal line feeds and not inform the computer internal line printer buffer. If 
this has happened, the value returned by LPOS(x) may be incorrect. LPOS(x) 
simply counts the number of printable characters since the last line feed was 
issued. 


Examples: 


The following line causes a carriage return after the 60th character is printed on 
a line: 


100 IF LPOS(X)>60 THEN LPRINT CHR$ (13) 
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LPRINT and LPRINT USING Statements 
Purpose: 


To print data at the line printer. 


Syntax: 


LPRINT [list of expressions][;] 
LPRINT USING string exp; list of expressions{[;] 


Comments: 


list of expressions consists of the string or numeric expression separated by 
semicolons. 


string expressions is a string literal or variable consisting of special formatting 
characters. The formatting characters determine the field and the format of 
printed strings or numbers. 


These statements are the same as PRINT and PRINT USING, except that 
output goes to the line printer. For more information about string and numeric 


fields and the variables used in them, see the PRINT and PRINT USING 
statements. 


The LPRINT and LPRINT USING statements assume that your printer is an 
80-character-wide printer. 


To reset the number of characters that you can print across the printed page 
(assuming that your printer is wider than 80 characters), see the WIDTH 
statement. 
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LSET and RSET Statements 


Purpose: 


To move data from memory to a random-file buffer and left- or right-justify it 
in preparation for a PUT statement. 


Syntax: 


LSET string variable=string expression 
RSET string variable=string expression 


Comments: 


If string expression requires fewer bytes than were fielded to string variable, 
LSET left-justifies the string in the field, and RSET right-justifies the string 
(spaces are used to pad the extra positions). 


If the string is too long for the field, characters are dropped from the right. 


To convert numeric values to strings before the LSET or RSET statement is 
used, see the MKI$, MKS$, and MKD$ functions. 


LSET or RSET may also be used with a nonfielded string variable to left- 
justify or right-justify a string in a given field. 


Examples: 


110 AS=SPACES (20) 
120 RSET AS=N$ 


These two statements right-justify the string N$ in a 20-character field. This 
can be valuable for formatting printed output. 
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MERGE Command 


Purpose: 


To merge the lines from an ascii program file into the program already in 
memory. 


Syntax: 


MERGE filename 


Comments: 


filename is a valid string expression containing the filename. If no extension is 
specified, then Gw-BAsic assumes an extension of .BAS. 


The diskette is searched for the named file. If found, the program lines on the 
diskette are merged with the lines in memory. After the MERGE command, the 
merged program resides in memory, and Gw-Basic returns to the direct mode. 

If the program being merged was not saved in ascii code with the a option to 
the SAVE command, a "Bad file mode” error is issued. The program in 
memory remains unchanged. 

If any line numbers in the file have the same number as lines in the program in 
memory, the lines from the file replace the corresponding lines in memory. 


Examples: 


MERGE "SUBRTN" 


Merges the file subrin.bas with the program currently in memory, provided 
subrm was previously saved with the a option. If some of the program lines are 
the same as those in the subrtn.bas file being merged, then the original program 
lines are replaced by the lines from subrin.bas. 
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MID$ Function 


Purpose: 


To return a string of m characters from v$ beginning with the nth character. 


Syntax: 
MID$ (x$,n[,m]) 


Comments: 


n must be within the range of 1 to 255. 
m must be within the range of 0 to 255. 


If m is omitted, or if there are fewer than m characters to the right of n, all 
rightmost characters beginning with n are returned. 


If n>LEN(x$), MID$ function returns a null string. 

If m equals 0, the MID$ function returns a null string. 

If either n or m is out of range, an "Ilegal function call error” is returned. 
For more information and examples, see the LEFT$ and RIGHTS functions. 


Examples: 


10 AS="GOOD" 

20 BS="MORNING EVENING AFTERNOON" 
30 PRINT AS$;MIDS (BS, 8,8) 

RUN 

GOOD EVENING 

Ok 


Line 30 concatenates (joins) the A$ string to another string with a length of 
eight characters, beginning at position 8 within the B$ string. 
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MID$ Statement 
Purpose: 


To replace a portion of one string with another string. 


Syntax: 


MID$(stringexp1 ,n[,m])=stringexp2 


Comments: 


Both n and m are integer expressions. 

stringexp! and stringexp2 are string expressions. 

The characters in stringexp/, beginning at position n, are replaced by the 
characters in stringexp2. 

The optional m refers to the number of characters from stringexp2 that are used 
in the replacement. If m is omitted, all of stringexp2 is used. 


Whether m is omitted or included, the replacement of characters never goes 
beyond the original length of stringexp1!. 


Examples: 


10 A$="KANSAS CITY, MO" 
20 MIDS (A$, 14)="KS" 

30 PRINT AS 

RUN 

KANSAS CITY, KS 

Ok 


Line 20 overwrites "MO" in the A$ string with "KS". 
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MKDIR Command 
Purpose: 

To create a subdirectory. 
Syntax: 


MKDIR pathname 


Comments: 


pathname is a string expression, not exceeding 63 characters, identifying the 
subdirectory to be created. 


Examples: 


MKDIR "C:SALES\JOHN" 


Creates the subdirectory john within the directory of sales. 
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MKI$, MKS$, MKD$ Functions 
Purpose: 


To convert numeric values to string values. 
Syntax: 


MKI$(integer expression) 
MKS{(single-precision expression) 
MKD§(double-precision expression) 


Comments: 


MKIŞ converts an integer to a 2-byte string. 
MKSS$ converts a single-precision number to a 4-byte string. 
MKDS converts a double-precision number to an 8-byte string. 


Any numeric value placed in a random file buffer with a LSET or a RSET 
statement must be converted to a string (see CVI, CVS, CVD, for the 
complementary functions). 


These functions differ from STR$ because they change the interpretations of 
the bytes, not the bytes themselves. 


Examples: 


90 AMT=(K+T) 

100 FIELD #1,8 AS D$,20 AS N$ 
110 LSET DS=MKSS (AMT) 

120 LSET NS=AS 

130 PUT #1 
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NAME Command 


Purpose: 
To change the name of a disk file. 


Syntax: 


NAME old filename AS new filename 


Comments: 


old filename must exist and new filename must not exist; otherwise, an error 
results, 


After a NAME command, the file exists on the same diskette, in the same disk 
location, with the new name. 


Examples: 


NAME “ACCTS" AS "LEDGER" Ok 


The file formerly named accts will now be named ledger. The file content and 
physical location on the diskette is unchanged. 
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NEW Command 


Purpose: 


To delete the program currently in memory and clear all variables. 


Syntax: 


NEW 


Comments: 


NEW is entered at command level to clear memory before entering a new 
program. Gw-BASIc always returns to command level after a NEW is executed. 


Examples: 


NEW 
OK 


or 


980 PRINT "Do You Wish To Quit (Y/N) 
990 ANSS=INKEYS: IF ANSS=""THEN 990 
1000 IF ANS$="Y" THEN NEW 

1010 IF ANSS="N" THEN 980 

1020 GOTO 990 
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OCTS$ Function 


Purpose: 


To convert a decimal value to an octal value. 


Syntax: 


OCTS$(x) 


Comments: 


x is rounded to an integer before OCT$(x) is evaluated. 


This statement converts a decimal value within the range of -32768 to +65535 
to an octal string expression. 

Octal numbers are numbers to the base 8 rather than base 10 (decimal 
numbers). 


See the HEX$S function for hexadecimal conversion. 


Examples: 


10 PRINT OCT$ (18) 
RUN 
22 
Ok 


Decimal 18 equals octal 22. 
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ON COM(n), ON KEY(n), ON PEN, ON 
PLAY(n), ON STRIG(n), and ON TIMER(n) 
Statements 

Purpose: 


To create an event trap line number for a specified event (such as 
communications, pressing function or cursor control keys, using the light pen, 
or using joysticks). 


Syntax: 


ON event specifier GOSUB line number 


Comments: 


The syntax shown sets up an event trap line number for the specified event. A 
line number of 0 disables trapping for this event. 


Once trap line numbers have been set, event trapping itself can be controlled 
with the following syntax lines: 


event specifier ON When an event is ON, and a nonzero line 
number is specified for the trap, then every 
time BASIC starts a new statement, it 
checks to see if the specified event has 
occurred. if it has, BASIC performs a 
GOSUB to the line specified in the ON 


statement. 

event specifier OFF When an event is OFF, no trapping occurs 
and the event is not remembered, even if it 
occurs. 

event specifier STOP When an event is stopped, no trapping can 


occur, but if the event happens, it is 
remembered so an immediate trap occurs 
when an event specifier ON is executed. 


When a trap is made for a particular event, the trap automatically causes a stop 
on that event, so recursive traps can never take place. 

The return from the trap routine automatically does an ON unless an explicit 
OFF has been performed inside the trap routine. 
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When an error trap takes place, this automatically disables all trapping. 
Trapping will never take place when BASIC is not executing a program. 


The following are valid values for event specifier: 


COM(n) 


KEY(n) 


PEN 


PLAY(n) 


STRIG(n) 


TIMER(n) 


RETURN line number 


nis the number of the COM channel (1 or 
2). 


nis a function key number 1-20. 1 through 
10 are the function keys F1 through F10. 11 
through 14 are the cursor control keys as 
follows: 


11= Cursor Up 13= Cursor Right 
12= Cursor Left 14= Cursor Down 
15-20 are user-defined keys. 


Since there is only one pen, no number is 
given. 


nis an integer expression in the range of 1- 
32. Values outside this range result in 
"Illegal function call" errors. 


nis 0, 2, 4 or 6. (O=tngger A1; 4=trigger 
A2; 2=trigger B1; 6=trigger B2). 


n is a numeric expression within the range of 
1 to 86,400. A value outside of this range 
results in an "Illegal function call" error. 


This optional form of RETURN is primarily 
intended for use with event trapping. The 
event-trapping routine may want to go back 
into the Gw-BAsic program at a fixed line 
number while still eliminating the GOSUB 
entry that the trap created. 


Use of the nonlocal RETURN must be done 
with care. Any other GOSUB, WHILE, or 
FOR that was active at the time of the trap 
remains active. 


If the trap comes out of a subroutine, any 
attempt to continue loops outside the 
subroutine results ina "NEXT without 
FOR" error. 
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Special Notes About Each Type of Trap 
COM Trapping 


Typically, the COM trap routine will read an entire message from the COM 
port before returning. 


It is recommended that you not use the COM trap for single character 
messages, since at high baud rates the overhead of trapping and reading for 
each individual character may allow the interrupt buffer for COM to overflow. 


KEY Trapping 


Trappable keys 15 to 20 are defined by the following statement: 
KEY(n),CHR$[hexcode]+CHR$[scan code] 


nis an integer expression within the range of 15 to 20 defining the key to be 
trapped. 

hexcode is the mask for the latched key: (CAPs LOCK, NUM LOCK, ALT, CTRL, LEFT SHIFT, 
RIGHT SHIFT) 

scan code is the number identifying one of the 83 keys to trap. Refer to 
Appendix H in the GW-BASIC User's Guide for key scan codes. 


The appropriate bit in hexcode must be set in order to trap a key that is shifted, 
control-shifted, or alt-shifted. hexcode values are as follows: 


Mask Hexcode Indicates that 

EXTENDED &H80 Key is extended 

CAPS LOCK &H40 CAPS LOCK is active 

NUM LOCK &H20 NUM LOCK is active 

ALT &HO08 The aLr key is pressed 

CTRL &H04 The crrt key is pressed 
LEFT SHIFT &H02 The left suirr key is pressed 


RIGHT SHIFT &HO01 The right sur key is pressed 
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For trapping shifted keys, you may use the value &H01, &H02, or &H03. The 
left and right srt keys are coupled when &H03 is used. 


Refer to the KEY(n) statement for more information. 


No type of trapping is activated when cw-nasic is in direct mode. Function keys 
resume their standard expansion meaning during input. 


A key that causes a trap is not available for examination with the INPUT or 
INKEY$ statement, so the trap routine for each key must be different if a 
different function is desired. 


If CTRL-PRTSC is trapped, the line printer echo toggle is processed first. Defining 
CTRL-PRTSC as a key trap does not prevent characters from being echoed to the 
printer if crTRL-PRTSC is pressed. 


Function keys 1 through 14 are predefined. Therefore, setting scan codes 59-68, 
72, 75, 77, or 80 has no effect. 


PLAY(n) Trapping 


A PLAY event trap is issued only when playing background music 
(PLAY"MB..). PLAY event music traps are not issued when running in 
MUSIC foreground (default case, or PLAY" MF. . ). 


Choose conservative values for n. An ON PLAY(32).. statement will cause 
event traps so often that there will be little time to execute the rest of your 
program. 

The ON PLAY(n) statement causes an event trap when the background music 
queue goes from n to n-1 notes. 


STRIG Trapping 


Using STRIG(n) ON activates the interrupt routine that checks the trigger 
status. Downstrokes that cause trapping will not set STRIG(0), STRIG(2), 
STRIG(4), or STRIG(6) functions. 
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TIMER(n) Trapping 


An ON TIMER(n) event trapping statement is used with applications needing 
an internal timer. The trap occurs when n seconds have elapsed since the 
TIMER ON statement. 


Example 1: 
This is a very simple terminal program. 


10 REM "ON COM(n)" EXAMPLE 

20 OPEN "COM1:9600,0,7" AS #1 

30 ON COM(1) GOSUB 80 

40 COM(1) ON 

50 REM TRANSMIT CHARACTERS FROM KEYBOARD 
60 AS=INKEYS$:IF AS=""THEN 50 

70 PRINT #1,A$;:GOTO 50 

80 REM DISPLAY RECEIVE CHARACTERS 

90 ALL=LOC (1) :IF ALL<1 THEN RETURN 

100 BS=INPUTS (ALL, #1) :PRINT BS; :RETURN 


Example 2: 


Prevents a CTRL-BREAK or system reset during a program. 


10 KEY 15,CHRS$ (4) +CHR$(70) REM Trap “BREAK 

20 KEY 16,CHR$(12)+CHRS$ (83) REM Trap system reset 
30 ON KEY(15) GOSUB 1000 

40 ON KEY(16) GOSUB 2000 

50 KEY(15) ON 

60 KEY(16) ON 


1000 PRINT "I’m sorry, I can’t let you do that" 
1010 RETURN 

2000 ATTEMPS=ATTEMPS+1 

2010 ON ATTEMPS GOTO 2100, 2200, 2300, 2400, 2500 
2100 PRINT "Mary had a little lamb":RETURN 

2200 PRINT "Its fleece was white as snow":RETURN 
2300 PRINT "And everywhere that Mary went":RETURN 
2400 PRINT "The lamb was sure to go":RETURN 2500 
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KEY (16) OFF REM If they hit us once more... 
2510 RETURN REM then BASIC dies... 


Example 3: 


Displays the time of day on line 1 every minute. 


10 ON TIMER(60) GOSUB 10000 
20 TIMER ON 


10000 OLDROW=CSRLIN REM Saves the current row 
10010 OLDCOL=P0S(0) REM Saves the current column 
10020 LOCATE 1,1:PRINT TIMES 

10030 LOCATE OLDROW, OLDCOL REM Restores row and 
column 

10040 RETURN 
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ON ERROR GOTO Statement 


Purpose: 


To enable error trapping and specify the first line of the error-handling 
subroutine. 


Syntax: 
ON ERROR GOTO line number 


Comments: 


Once error trapping has been enabled, all errors detected by cw-nasic, including 
direct mode errors, (for example, syntax errors) cause Gw-Basic to branch to the 
line in the program which begins the specified error-handling subroutine. 


Gw-Basic branches to the line specified by the ON ERROR statement until a 
RESUME statement is found. 


If line number does not exist, an "Undefined line" error results. 
To disable error trapping, execute the following statement: 


ON ERROR GOTO 0 


Subsequent errors print an error message and halt execution. 


An ON ERROR GOTO 0 statement in an error-trapping subroutine causes Gw- 
BASIC to stop and print the error message for the error that caused the trap. It is 
recommended that all error-trapping subroutines execute an ON ERROR 
GOTO 0 if an error is encountered for which there is no recovery action. 


If an error occurs during execution of an error-handling subroutine, the Gw-BAsIC 
error message is printed and execution terminated. Error trapping does not 
occur within the error-handling subroutine. 


Examples: 


10 ON ERROR GOTO 1000 


1000 A=ERR: B=ERL 
1010 PRINT A,B 
1020 RESUME NEXT 
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Line 1010 prints the type and location of the error on the screen (see the ERR 
and ERL variables). 

Line 1020 causes program execution to continue with the line following the 
error. 
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ON ... GOSUB and ON ... GOTO Statements 


Purpose: 


To branch to one of several specified line numbers, depending on the value 
returned when an expression is evaluated. 


Syntax: 


ON expression GOTO line numbers 
ON expression GOSUB line numbers 


Comments: 


In the ON ... GOTO statement, the value of expression determines which line 
number in the list will be used for branching. For example, if the value is 3, the 
third line number in the list will be destination of the branch. If the value is a 
noninteger, the fractional portion is rounded. 


In the ON ... GOSUB statement, each line number in the list must be the first 
line number of a subroutine. 


If the value of expression is zero or greater than the number of items in the list 
(but less than or equal to 255), cw-Basic continues with the next executable 
statement. 


If the value of expression is negative, or greater than 255, an "Illegal function 
call” error occurs. 


Examples: 


100 IF R<1 or R>4 then print "ERROR":END 


If the integer value of R is less than 1, or greater than 4, program execution 
ends. 


200 ON R GOTO 150, 300,320,390 


If R=1, the program goes to line 150. 


If R=2, the program branches to line 300 and continues from there. If R=3, the 
branch will be to line 320, and so on. 
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OPEN Statement 
Purpose: 
To establish input/output (I/O) to a file or device. 


Syntax: 


OPEN mode,[#) file number filename[,reclen] 


OPEN filename [FOR mode] [ACCESS access) [lock] AS [#]ftle number 
[LEN=reclen] 


Comments: 


filename is the name of the file. 
mode (first syntax) is a string expression with one of the following characters: 


Expression Specifies 

O Sequential output mode 

I Sequential input mode 

R Random input/output mode 
A Position to end of file 


mode (second syntax) determines the initial positioning within the file, and the 
action to be taken if the file does not exist. If the FOR mode clause is omitted, 
the initial position is at the beginning of the file. If the file is not found, one is 
created. This is the random I/O mode. That is, records may be read or written at 
any position within the file. The valid modes and actions taken are as follows: 


INPUT Position to the beginning of the file. A "File not 
found” error is given if the file does not exist. 
OUTPUT Position to the beginning of the file. If the file does not 


exist, one is created. 
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APPEND Position to the end of the file. If the file does not exist, 
one is created. 
RANDOM Specifies random input or output mode. 


mode must be a string constant. Do not enclose mode in double quotation 
marks. access can be one of the following: 


READ 
WRITE 
READ WRITE 


file number is a number between 1 and the maximum number of files allowed. 
The number associates an I/O buffer with a disk file or device. This association 
exists until a CLOSE or CLOSE file number statement is executed. 


reclen is an integer expression within the range of 1-32767 that sets the record 
length to be used for random files. If omitted, the record length defaults to 128- 
byte records. 

When reclen is used for sequential files, the default is 128 bytes, and reclen 
cannot exceed the value specified by the /s switch. 

A disk file must be opened before any disk I/O operation can be performed on 
that file. OPEN allocates a buffer for I/O to the file and determines the mode of 
access that is used with the buffer. 


More than one file can be opened for input or random access at one time with 
different file numbers. For example, the following statements are allowed: 


OPEN "B: TEMP" FOR INPUT AS #1 
OPEN "B:TEMP" FOR INPUT AS #2 


However, a file may be opened only once for output or appending. For 
example, the following statements are illegal: 


OPEN "TEMP" FOR OUTPUT AS #1 
OPEN "TEMP" FOR OUTPUT AS #2 
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Note Be sure to close all files before removing diskettes from the disk drives 
(see CLOSE and RESET). 


A device may be one of the following: 


A:,B:,C:... Disk Drive 

KYBD: Keyboard (input only) 

SCRN: Screen (output only) 

LPT1: Line Printer 1 

LPT2: Line Printer 2 

LPT3: Line Printer 3 

COM1: RS-232 Communications 1 
COM?: RS-232 Communications 2 

For each device, the following OPEN modes are allowed: 
KYBD: Input Only 

SCRN: Output Only 

LPT1: Output Only 

LPT2: Output Only 

LPT3: Output Only 

COM1: Input, Output, or Random Only 
COM2: Input, Output, or Random Only 


Disk files allow all modes. 


When a disk file is opened for APPEND, the position is initially at the end of 
the file, and the record number is set to the last record of the file (LOF(x)/128). 
PRINT, WRITE, or PUT then extends the file. The program may position 
elsewhere in the file with a GET statement. If this is done, the mode is changed 
to random and the position moves to the record indicated. 
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Once the position is moved from the end of the file, additional records may be 
appended to the file by executing a GET #x, LOF(x)/reclen statement. This 
positions the file pointer at the end of the file in preparation for appending. 


Any values entered outside of the ranges given result in "legal function call" 
errors. The files are not opened. 


If the file is opened as INPUT, attempts to write to the file result in "Bad file 
mode" errors. 


If the file is opened as OUTPUT, attempts to read the file result in "Bad file 
mode” errors. 


Opening a file for OUTPUT or APPEND fails, if the file is already open in any 
mode. 


Since it is possible to reference the same file in a subdirectory via different 
paths, it is nearly impossible for Gw-Basic to know that it is the same file simply 
by looking at the path. For this reason, cw-Basic does not let you open the file 
for OUTPUT or APPEND if it is on the same disk, even if the path is different. 
For example if mary is your working directory, the following statements all 
refer to the same file: 


OPEN "REPORT" 

OPEN "\SALES\MARY\REPORT" 
OPEN "..\MARY\REPORT" 
OPEN "..\..\MARY\REPORT" 


At any one time, it is possible to have a particular diskette filename open under 
more than one file number. Each file number has a different buffer, so several 
records from the same file may be kept in memory for quick access. This 
allows different modes to be used for different purposes; or, for program 
clarity, different file numbers to be used for different modes of access. 


If the LEN=reclen option is used, reclen may not exceed the value set by the 
/s:reclen switch option in the command line. 


In a network environment, the use of the OPEN statement is based upon two 
different sets of circumstances: 


e Devices may be shared on a network for specific purposes only, so that 
OPEN statements may be restricted to specific modes among those which 
might be requested, such as: INPUT, OUTPUT, APPEND, and default 
(Random). 
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e _ Files may be restricted by the implementation of an OPEN statement 
which allows a process to specify an access to the successfully opened 
file. The access determines a guaranteed exclusivity range on that file by 
the process while the OPEN statement is in effect. 


lock can be one of the following: 


SHARED 


LOCK READ 


LOCK WRITE 


LOCK READ 


default 


“deny none" mode. No restrictions are placed on the 
read/write accessibility of the the file to another process, 
except that the default mode is not allowed by any of the 
modes including SHARED. 


"deny read" mode. Once a file is opened with the LOCK 
READ access, no other process is granted read-access to 
that file. An attempt to open a file with this access will be 
unsuccessful, if the file is currently open in default mode 
or with a read access. 


"deny write” mode. A file successfully opened with LOCK 
WRITE access may not be opened for a write access by 
another process. An attempt to open a file with this access 
will be unsuccessful if the file has been opened in default 
mode, or with a write access by another process. 


"deny all" or “exclusive” mode. If a file is successfully 
WRITE opened with this access, the process has exclusive 
access to the file. A file that is currently open in this mode 
cannot be opened again in any mode by any process. 
"compatibility" mode, in which the compatibility with 
other Basics is understood. No access is specified. The file 
may be opened any number of times by a process, 
provided that the file is not currently opened by another 
process. Other processes are denied access to the file while 
it is open under default access. Therefore, it is functionally 
exclusive. 


When an attempt is made to open a file that has been previously accessed by 
another process, the error "Permission Denied” will result. An example of a 
situation generating this error is when a process attempts to OPEN SHARED 
on a file that is already OPEN LOCK READ WRITE by another process. 
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If an OPEN statement fails because the mode is incompatible with 
networkinstalled sharing access to a device, the error generated is "Path/File 
Access Error.” An example of this is when a process is attempting to OPEN a 
file for output on a directory that has been shared for read only. 


For more information about using files in a networking environment, see the 
LOCK and UNLOCK statements. 


Examples: 


10 OPEN "I",2,"INVEN" 


Opens file 2, inven, for sequential input. 
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OPEN "COM(n) Statement 
Purpose: 


To allocate a buffer to support RS-232 asynchronous communications with 
other computers and peripheral devices in the same manner as OPEN for disk 


files. 


Syntax: 


OPEN "COM[n]:[speed][ parity][,data] [,stop}[,RS][,CS[n]][,DS[n]] 
[,CD[n]][,LF] [[PE]" AS [#]filenwn (LEN=number) 


Comments: 


COM|[n] is a valid communications device: com1: or com2:. 

speed is a literal integer specifying the transmit/receive baud rate. 

Valid speeds are as follows: 

75, 110, 150, 300, 600, 1200, 1800, 2400, 4800, and 9600. The default is 300 
bps. 

parity is a one-character literal specifying the parity for transmitting and 
receiving. 

Valid characters specifying parity are as follows: 


S SPACE. Parity bit always transmitted and received as space (0 bit). 

M MARK. Parity bit always transmitted and received as mark (1 bit). 

O ODD. Odd transmit parity; odd receive parity checking. Default is 
even. 

E EVEN. Even transmit parity; even receive parity checking. Even is 
default. 

N NONE. No transmit parity. No receive parity checking. 


data is a literal integer indicating number of transmit/receive data bits. 
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Valid values for the number of data bits are 4, 5, 6, 7, or 8, the default is 7 bits. 


Note Four data bits with no parity is illegal; eight data bits with any parity is 
illegal. 


stop is a literal integer expression returning a valid file number. 


Valid values for number of stop bits are 1 and 2. If omitted, 75 and 110 bps 
transmit two stop bits. All others transmit one stop bit. 


filenum is a number between 1 and the maximum number of files allowed. A 
communications device may be opened to only one file number at a time. 


The filenum is associated with the file for as long as the file is open, and is used 
to refer other COM I/O statements to the file. 


Any coding errors within the filename string result in "Bad file name" errors. 
An indication as to which parameters are in error is not given. 


number is the maximum number of bytes which can be read from the 
communications buffer when using GET or PUT default of 128 bytes. 


A "Device timeout" error occurs if “data set ready" (DSR) is not detected. 
The RS, CS, DS, DC, LF, and PE options affect the line signals as follows: 


Option Function 

RS suppresses RTS (request to send) 
CS[n} controls CTS (clear to send) 
DS[n] controls DSR (data set ready) 
CD{[n] controls CD (carrier detect) 

LF sends a line feed at each return 


PE enables parity checking 
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n is the number of milliseconds to wait (0-65535) for that signal before a device 
timeout error occurs. Defaults are: CS1000, DS1000, and CDO. If RS was 
specified then CSO is the default. If n is omitted, then timeout is set to 0. 


See Appendix F in the GW-BASIC User's Guide for more information about 
communications. 


Examples: 


In the following, File 1 is opened for communications with all defaults: speed 
at 300 bps, even parity, seven data bits, and one stop bit. 


10 OPEN "COM1:" AS 1 


In the following, File 2 is opened for communications at 2400 bps. Parity and 
number of data bits are defaulted. 


20 OPEN "COM1:2400" AS #2 


In the following, File 1 is opened for asynchronous I/O at 1200 bits/second. No 
parity is to be produced or checked. 


10 OPEN "COM1:1200,N,8" AS #1 
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OPTION BASE Statement 


Purpose: 


To declare the minimum value for array subscripts. 


Syntax: 


OPTION BASE n 


Comments: 


nis 1 or 0. The default base is 0. 

If the statement OPTION BASE 1 is executed, the lowest value an array 
subscript can have is 1. 

An array subscript may never have a negative value. 

OPTION BASE gives an error only if you change the base value. This allows 


chained programs to have OPTION BASE statements as long as the value is 
not changed from the initial setting. 


Note You must code the OPTION BASE statement before you can define or 
use any arrays. If an attempt is made to change the option base value after 
any arrays are in use, an error results. 
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OUT Statement 


Purpose: 


To send a byte to a machine output port. 


Syntax: 


OUT h,j 


Comments: 


h and j are integer expressions. h may be within the range of 0 to 65535. j may 
be within the range of 0 to 255. h is a machine port number, and j is the data to 
be transmitted. 


OUT is the complementary statement to the INP function. 


Examples: 


100 OUT 12345,225 


Outputs the decimal value 225 to port number 12345. In assembly language, 
this is equivalent to the following: 
MOV DX,12345 


MOV AL, 255 
OUT DX, AL 
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PAINT Statement 
Purpose: 


To fill in a graphics figure with the selected attribute. 


Syntax: 


PAINT (x start,y start)[,paint attribute[,border attribute][,bckgrnd attribute)] 


Comments: 


The PAINT statement fills in an arbitrary graphics figure of the specified 
border attribute with the specified paint attribute. If paint attribute is not given, 
it will default to the foreground attribute (3 or 1). border attribute defaults to 
paint attribute. See the COLOR and PALETTE statements for more 
information. 

PAINT must start on a nonborder point, otherwise, PAINT will have no effect. 
PAINT can fill any figure, but painting jagged edges or very complex figures 
may result in an "Out of memory” error. The CLEAR statement may be used to 
increase the amount of stack space available. 


Points that are specified outside the limits of the screen will not be plotted and 
no error will occur. 


See the SCREEN statement for a description of the different screen modes. 


Paint Tiling 


PAINT tiling is similar to LINE styling. Like LINE, PAINT looks at a tiling 
mask each time a point is put down on the screen. 


If paint attribute is omitted, the standard foreground attribute is used. 


If paint attribute is a numeric formula, then the number must be a valid color, 
and it is used to paint the area as before. 
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If paint attribute is a string formula, then tiling is performed as follows: 


The tile mask is always eight bits wide and may be from 1 to 64 bytes long. 
Each byte in the tile string masks eight bits along the x axis when putting down 
points. Each byte of the tile string is rotated as required to align along the y 
axis, such that: 


tile_byte_mask=y MOD tile_length 


where y is the position of the graphics cursor on the y-axis. 


tile_length is the length in bytes of the tile string defined by the user (1 to 64 
bytes). 

This is done so that the tile pattern is replicated uniformly over the entire screen 
(as if a PAINT (0,0).. were used). 


x Increases --> Bit of Tile Byte 


X,Y 87654321 

0,0 [x|x|x|x|x|x|x|x| Tile byte 1 
0,1 |x|x|x|x|x|x]x|x| Tile byte 2 
0,2 [x|x[x|x|x|x|x|x| Tile byte 3 


0,63 |x|x|x|x|x|x|x|x]| Tile byte 64 
(maximum allowed) 


In high-resolution mode (SCREEN 2), the screen can be painted with Xs by the 
following statement: 


PAINT (320,100) ,CHR$ (&H81)+CHRS (&H42) +CHRS (&H24) + 
CHRS$ (&H18) +CHR$ (&H18) +CHR$ (&H24) +CHRS (&H81) 


This appears on the screen as follows: 


x increases --> 

0,0 Ix! | | | | | xl CHRS$(&H81) Tile byte 1 
0,1 | Ix! | | | Ix| | CHRS$(&H42) Tile byte 2 
0,2 | | Ix| | Ix} | | CHRS$(&H24) Tile byte 3 
0,3 | | | kxtxt | | | CHRS$(&H18) Tile byte 4 
0,4 | | | Ixix] | | | CHRS$ (&H18) Tile byte 5 
0,5 | Ixt | Ix] | | CHRS$(&H24) Tile byte 6 
0,6 | Ix! | | | Ix] | CHR$(&H42) Tile byte 7 
0,7 Ix} | | | | | |x| CHR$(&H81) Tile byte 8 


166 GW-BASIC User's Reference 


Since there are two bits per pixel in medium-resolution mode (SCREEN 1), 
each byte of the tile pattern only describes four pixels. In this case, every two 
bits of the tile byte describes one of the four possible colors associated with 
each of the four pixels to be put down. 


bckgrnd attribute specifies the background tile pattern or color byte to skip 
when checking for boundary termination. bckgrnd attribute is a string formula 
returning one character. When omitted, the default is CHR$(0). 


Occasionally, you may want to paint tile over an already painted area that is the 
same color as two consecutive lines in the tile pattern. PAINT quits when it 
encounters two consecutive lines of the same color as the point being set (the 
point is surrounded). It is not possible to draw alternating blue and red lines on 
a red background without bckgrnd attribute. PAINT stops as soon as the first 
red pixel is drawn. By specifying red (CHR$(&HAA)) as the background 
attribute, the red line is drawn over the red background. 


You cannot specify more than two consecutive bytes in the tile string that 
match the background attribute. Specifying more than two results in an "Illegal 
function call" error. 


Examples: 


10 CLS 

20 SCREEN 1 

30 LINE (0,0)-(100,150),2,B 
40 PAINT (50,50),1,2 

50 LOCATE 20,1 


The PAINT statement in line 40 fills in the box drawn in line 30 with color 1. 
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PALETTE, PALETTE USING Statements 


Purpose: 


Changes one or more of the colors in the palette 


Syntax: 


PALETTE [attribute,color] 
PALETTE USING integer-array-name (arrayindex) 


Comments: 


The PALETTE statement works only for systems equipped with the IBM ® 
Enhanced Graphics Adapter (EGA). A Gw-sasic palette contains a set of colors, 
with each color specified by an attribute. Each attribute is paired with an actual 
display color. This color determines the actual visual color on the screen, and is 
dependent on the setting of your screen mode and your actual physical 
hardware display. 


PALETTE with no arguments sets the palette to a known initial setting. This 
setting is the same as the setting when colors are first initialized. 


If arguments are specified, color will be displayed whenever attribute is 
specified in any statement that specifies a color. Any color changes on the 
screen occur immediately. Note that when graphics statements use color 
arguments, they are actually referring to attributes and not actual colors. 
PALETTE pairs attributes with actual colors. 


For example, assume that the current palette consists of colors 0, 1, 2, and 3. 
The following DRAW statement: 


DRAW "C3L100" 


selects attribute 3, and draws a line of 100 pixels using the color associated 
with the attribute 3, in this case, also 3. If the statement: 


PALETTE 3,2 


is executed, then the color associated with attribute 3 is changed to color 2. All 
text or graphics currently displayed on the screen using attribute 3 are 
instantaneously changed to color 2. All text or graphics subsequently displayed 
with attribute 3 will also be displayed in color 2. The new palette of colors will 
contain 0, 1, 2, and 2. 
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With the USING option, all entries in the palette can be modified in one 
PALETTE statement. The integer-array-name argument is the name of an 
integer array, and the arrayindex specifies the index of the first array element in 
the integer-array-name to use in setting your palette. Each attribute in the 
palette is assigned a corresponding color from this integer array. The array 
must be dimensioned large enough to set all the palette entries after arrayindex. 
For example, if you are assigning colors to all 16 attributes, and the index of 
the first array element given in your PALETTE USING statement is 5, then the 
array must be dimensioned to hold at least 20 elements (since the number of 
elements from 5-20, inclusive, is 16): 


DIM PAL% (20) 


PALETTE USING PAL% (5) 


If the color argument in an array entry is -1, then the mapping for the 
associated attribute is not changed. All other negative numbers are illegal 
values for color. 


You can use the color argument in the COLOR statement to set the default text 
color. (Remember that color arguments in other BASIC statements are actually 
what are called attributes in this discussion.) This color argument specifies the 
way that text characters appear on the display screen. Under a common initial 
palette setting, points colored with the attribute 0 appear as black on the display 
screen. Using the PALETTE statement, you could, for example, change the 
mapping of attribute 0 from black to white. 


Remember that a PALETTE statement executed without any parameters 
assigns all attributes their default colors. 
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The following table lists attribute and color ranges for various monitor types 
and screen modes: 


Table 1 

SCREEN Color and Attribute Ranges 

SCREEN Monitor Attribute Color 

Mode Attached Adapter Range Range 

0 Monochrome MDPA NA NA 
Monochrome EGA 0-15 0-2 
Color CGA NA 0-314 
Color/Enhancedd EGA 0-31a 0-15 

1 Color CGA NA 0-3 
Color/Enhancedd EGA 0-3 0-15 

2 Color CGA NA 0-1 
Color/Enhancedd EGA 0-1 0-15 

7 Color/Enhancedd EGA 0-15 0-15 

8 Color/Enhancedd EGA 0-15 0-15 

9 Enhancedd EGAD 0-3 0-15 
Enhancedd EGAc 0-15 0-63 

10 Monochrome EGA 0-3 0-8 


a Attributes 16-31 refer to blinking versions of colors 0-15 
b With 64K of EGA memory 

c With greater than 64K of EGA memory 

d IBM Enhanced Color Display 

NA = Not Applicable 

CGA = IBM Color Graphics Adapter 

EGA = IBM Enhanced Graphics Adapter 

MDPA = IBM Monochrome Display and Printer Adapter 


See the SCREEN statement reference page for the list of colors available for 
various SCREEN mode, monitor, and graphics adapter combinations. 
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Examples: 


PALETTE 0,2 ‘Changes all points colored with 
‘attribute 0 to color 2 


PALETTE 0,-1 ‘Does not modify the palette 


PALETTE USING A% (0) ‘Changes each palette entry. 
‘Since the array is initialized 
‘to zero when it is first 
‘declared, all attributes are 
‘now mapped to display color 
‘zero. The screen will now 
‘appear as one single color. 
‘However, it will still be 
‘possible to execute BASIC 
‘statements. 


PALETTE ‘Sets each palette entry to its appropriate 
‘initial display color. Actual initial 
‘colors depend on your screen hardware 
‘configuration. 
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PCOPY Command 

Purpose: 

To copy one screen page to another in all screen modes. 
Syntax: 


PCOPY sourcepage, destinationpage 


Comments: 


The sourcepage is an integer expression in the range 0 to n, where n is 
determined by the current video-memory size and the size per page for the 
current screen mode. 


The destinationpage has the same requirements as the sourcepage. 
For more information, see CLEAR and SCREEN. 


Examples: 


This copies the contents of page 1 to page 2: 
PCOPY 1,2 
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PEEK Function 


Purpose: 


To read from a specified memory location. 


Syntax: 


PEEK(a) 


Comments: 


Returns the byte (decimal integer within the range of 0 to 255) read from the 
specified memory location a. a must be within the range of 0 to 65535. 


The DEF SEG statement last executed determines the absolute address that will 
be peeked into. 
PEEK is the complementary function to the POKE statement. 


Examples: 


10 A=PEEK (&H5A00) 


The value of the byte, stored in user-assigned hex offset memory location 5A00 
(23040 decimal), will be stored in the variable A. 
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PEN Statement and Function 
Purpose: 


To read the light pen. 


Syntax: 


As a Statement: 


PEN ON 
PEN OFF 
PEN STOP 


As a function: 
x = P(n) 


Comments: 


x is the numeric variable receiving the PEN value. 
n is an integer within the range of 0 to 9. 

PEN ON enables the PEN read function. 

PEN OFF disables the PEN read function. 


PEN STOP disables trapping. It remembers the event so immediate trapping 
occurs when PEN ON is executed. 


x = PEN(n) reads the light pen coordinates. 


The PEN function is initially off. A PEN ON statement must be executed 
before any PEN read function calls can be made, or a PEN read function call 
results in an "Illegal function call" error. 


Light pen coordinates: 
n=0 If PEN was down since last poll, returns -1; if not, returns 0. 
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n=1 
n=2 
n=3 
n=4 
n=5 
n=6 
n=7 
n=8 
n=9 


Returns the x-pixel coordinate when PEN was last activated. 
The range is within 0 to 319 for medium resolution; 0 to 639, 
for high resolution. 

Returns the y-pixel coordinate when PEN was last activated. 
The range is within 0 to 199. 

Returns the current PEN switch value. Returns -1 if down; 0 if 
up. 

Returns the last known valid x-pixel coordinate. The range is 
within 0 to 319 for medium resolution; or 0 to 639 for high 
resolution. 

Returns the last known valid y-pixel coordinate. The range is 
within 0 to 199. 

Returns the character row position when PEN was last 
activated. The range is within 1 to 24. 

Returns the character column position when PEN was last 
activated. The range is within 1 to 40, or 1 to 80, depending on 
the screen width. 

Returns the last known valid character row. The range is within 
1 to 24. 

Returns the last known valid character column position. The 


range is within 1 to 40, or 1 to 80, depending on the screen 
width. 


For execution speed improvements, turn the pen off with a PEN OFF statement 
for those programs not using the light pen. 


When the pen is in the border area of the screen, the values returned will be 


inaccurate. 


Examples: 


50 PEN ON 


60 FOR I=1 to 500 
70 X=PEN (0) :X1=PEN (3) 
80 Print X,X1 


90 NEXT 


100 PEN OFF 


This example prints the pen value since the last poll and the current value. 
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PLAY Statement 

Purpose: 

To play music by embedding a music macro language into the string data type. 
Syntax: 


PLAY string expression 


Comments: 

A-G [#,+,-] A-G are notes. # or + following a note produces a sharp; - 
produces a flat. 
Any note followed by #,+,or - must refer to a black key on 
a piano. 

L(n) Sets the length of each note. L4 is a quarter note, L1 is a whole 


note, and so on. n may be from 1 to 64. 


Length may also follow the note to change the length for 
that note only. A16 is equivalent to L16A. 


MF Music foreground. PLAY and SOUND statements are to 
run in foreground. That is, each subsequent note or sound 


is not started until the previous note or sound is finished. 
This is the initial default. 


MB Music background. PLAY and SOUND statements are to 
run in background. That is, each note or sound is placed in 
a buffer allowing the BASIC program to continue 
execution while music plays in the background. As many 
as 32 notes (or rests) can be played in background at one 
time. 
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MN 


ML 
MS 


N(n) 
O(n) 
P(n) 


T(n) 


(period) 


Xstring; 


Music normal. Each note plays seven-eighths of the time 
determined by L (length). 
Music legato. Each note plays the full period set by L. 


Music staccato. Each note plays three-quarters of the time 
determined by L. 


Play note n. n may range from 0 to 84. In the 7 possible 
octaves, there are 84 notes. n set to 0 indicates a rest. 


Octave 0 sets the current octave. There are 7 octaves (0 
through 6). Default is 4. Middle C is at the beginning of 
octave 3, 


Pause. P may range from 1-64. 
Tempo. T sets the number of L4s in a minute. n may range 
from 32-255. Default is 120. 


A period after a note increases the playing time of the note 
by 3/2 times the period determined by L (length of note) 
times T (tempo). Multiple periods can appear after a note, 
and the playing time is scaled accordingly. For example, 
A. will cause the note A to play one and half times the 
playing time determined by L (length of the note) times T 
(the tempo); two periods placed after A (A..) will cause the 
note to be played at 9/4 times its ascribed value; an A with 
three periods (A...) at 27/8, etc. 


Periods may also appear after a P (pause), and increase the 
pause length as described above. 


Executes a substring, where string is a variable assigned to 
a string of PLAY commands. 


Because of the slow clock interrupt rate, some notes do not 
play at higher tempos; for example, 1.64 at T255. These 
note/tempo combinations must be determined through 
experimentation. 
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>n A greater-than symbol preceding the note n plays the note 
in the next higher octave. 


<n A less-than symbol preceding the note n plays the note in 
the next lower octave. 


Note Numeric arguments follow the same syntax described under the DRAW 
Statement. 


n as an argument can be a constant, or it can be a variable with = in front of it 
(= variable). A semicolon is required after the variable and also after the 
variable in Xstring. 
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PLAY(n) Function 
Purpose: 


To return the number of notes currently in the background music queue. 


Syntax: 


PLAY(n) 


Comments: 


nis adummy argument, and may be any value. 
PLAY(n) returns 0 when in music foreground mode. 
The maximum returned value of x is 32. 


Examples: 


10 ’ when 4 notes are left in 
20 ’ queue play another tune 
30 PLAY "MBABCDABCDABCD" 

40 IF PLAY (0) =4 then 200 


200 PLAY "MBCDEFCDEF" 
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PMAP Function (Graphics) 
Purpose: 

To map expressions to logical or physical coordinates. 
Syntax: 

x=PMAP (exp function) 

Comments: 


This function is valid for graphics modes only. 
x is the physical coordinate of the point that is to be mapped. 
exp is a numeric variable or expression. 


Function Maps 


0 logical expressions to physical x 
1 logical expressions to physical y 
2 physical expressions to logical x 
3 physical expressions to logical y 


PMAP is used with WINDOW and VIEW to translate coordinates. 
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POINT Function 


Purpose: 


To read the color or attribute value of a pixel from the screen. 


Syntax: 


POINT(G,y) 
POINT (function) 


Comments: 


In the first syntax, x and y are coordinates of the point to be examined. 
If the point given is out of range, the value -1 is returned. 
See the COLOR and PALETTE statements for valid color and attribute values. 


POINT with one argument allows you to retrieve the current graphics 
coordinates. 

POINT (function) returns the value of the current x or y graphics coordinates as 
follows: 


Function Returns 

0 the current physical x coordinate. 

1 the current physical y coordinate. 

2 the current logical x coordinate if WINDOW is active; 
otherwise, it returns the current physical x coordinate as in 0 
above. 

3 the current logical y coordinate if WINDOW is active; 


otherwise, it returns the current physical y coordinate as in 1 
above. 
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Example 1: 


10 
20 
30 
40 
50 


SCREEN 1 

FOR C=0 TO 3 

PSET (10,10),C 

IF POINT (10,10)<>C THEN PRINT "BROKEN BASIC=" 
NEXT C RUN 


Example 2: 


The following inverts the current state of a point: 


10 
20 


SCREEN 2 
IF POINT (I,1I)<>0 THEN PRESET(I,I) ELSE PSET(I,I) 


RUN 


Example 3: 


The following is another way to invert a point: 


20 


PSET (I,1I),1-POINT(I,TI) 


RUN 
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POKE Statement 


Purpose: 


To write (poke) a byte of data into a memory location. 


Syntax: 


POKE a,b 


Comments: 


a and b are integer expressions. 


The integer expression a is the offset address of the memory location to be 
poked. The DEF SEG statement last executed determines the address. Gw-BASIC 
does not check any offsets that are specified. 

The integer expression b is the data to be poked. 

b must be within the range of 0 to 255. a must be within the range of 0 to 
65535. 

The complementary function to POKE is PEEK. The argument to PEEK is an 
address from which a byte is to be read. 


POKE and PEEK are useful for efficient data storage, loading assembly 
language subroutines, and for passing arguments and results to and from 
assembly language subroutines. 


Examples: 


20 POKE &H5A00, &HFF 


Places the decimal value 255 (&HFF) into the hex offset location (23040 
decimal) See PEEK function example. 
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POS Function 
Purpose: 


To return the current cursor position. 


Syntax: 


POS(c) 


Comments: 


The leftmost position is 1. 
c is adummy argument. 


Examples: 


10 CLS 

20 WIDTH 80 

30 AS=INKEYS:IF A$=""THEN GOTO 30 ELSE PRINT A$; 
40 IF POS(X)>10 THEN PRINT CHR$ (13); 

50 GOTO 30 


Causes a carriage return after the 10th character is printed on each line of the 
screen. 
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PRESET and PSET Statements 
Purpose: 


To display a point at a specified place on the screen during use of the graphics 
mode. 


Syntax: 


PRESET(z,y)[,color] 
PSET(x,y)[, color] 


Comments: 


(x,y) represents the coordinates of the point. 
color is the color of the point. 
Coordinates can be given in either absolute or relative form. 


Absolute Form 


(absolute x, absolute y) is more common and refers directly to a point without 
regard to the last point referenced. For example: 


(10,10) 


Relative Form 


STEP (x offset, y offset) is a point relative to the most recent point referenced. 
For example: 


STEP (10,10) 


Coordinate values can be beyond the edge of the screen. However, values 
outside the integer range (-32768 to 32767) cause an "Overflow" error. 


(0,0) is always the upper-left corner and (0,199) is the lower-left corner in both 
high resolution and medium resolution. 
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See the COLOR and PALETTE statements for more information. 


If the value for color is greater than 3, an “Illegal function call” error is 
returned. 


Example 1: 


The following draws a diagonal line from (0,0) to (100,100). 


10 
20 
30 
40 
50 
60 


CLS 

SCREEN 1 

FOR I=0 TO 100 
PSET (I,II) 
NEXT 

LOCATE 14,1 


Example 2: 


The following clears out the line by setting each pixel to 0. 


40 FOR I=100 TO 0 STEP -1 
50 PSET(I,1I),0 
60 NEXT I 
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PRINT Statement 


Purpose: 


To output a display to the screen. 


Syntax: 


PRINT [list of expressions][;] 
?[list of expressions)[;] 


Comments: 


If list of expressions is omitted, a blank line is displayed. 


If list of expressions is included, the values of the expressions are displayed. 
Expressions in the list may be numeric and/or string expressions, separated by 
commas, spaces, or semicolons. String constants in the list must be enclosed in 
double quotation marks. 


For more information about strings, see the STRING$ function. 


A question mark (?) may be used in place of the word PRINT when using the 
GW-BASIC program editor. 


Print Positions 


Gw-BAsic divides the line into print zones of 14 spaces. The position of each 
item printed is determined by the punctuation used to separate the items in the 
list: 


Separator Print Position 
i Beginning of next zone 
; Immediately after last value 


space(s) Immediately after last value 
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If a comma, semicolon, or SPC or TAB function ends an expression list, the 
next PRINT statement begins printing on the same line, accordingly spaced. If 
the expression list ends without a comma, semicolon, or SPC or TAB function, 
a carriage return is placed at the end of the lines (Gw-nasic places the cursor at 
the beginning of the next line). 

A carriage return/line feed is automatically inserted after printing width 
characters, where width is 40 or 80, as defined in the WIDTH statement. This 
results in two lines being skipped when you print exactly 40 (or 80) characters, 
unless the PRINT statement ends in a semicolon. 


When numbers are printed on the screen, the numbers are always followed by a 
space. Positive number are preceded by a space. Negative numbers are 
preceded by a minus (-) sign. Single-precision numbers are represented with 
seven or fewer digits in a fixed-point or integer format. 


See the LPRINT and LPRINT USING statements for information on sending 
data to be printed on a printer. 


Examples: 


10 X$= STRINGS (10, 45) 
20 PRINT X$"MONTHLY REPORT" X$ 


45 is the decimal equivalent of the ascu symbol for the minus (-) sign. 
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PRINT USING Statement 
Purpose: 


To print strings or numbers using a specified format. 


Syntax: 


PRINT USING string expressions, list of expressions[;] 


Comments: 


string expressions is a string literal or variable consisting of special formatting 
characters. The formatting characters determine the field and the format of 
printed strings or numbers. 

list of expressions consists of the string or numeric expressions separated by 
semicolons. 


String Fields 


The following three characters may be used to format the string field: 


! Specifies that only the first character in the string is to be 
printed. 
Vi spaces\ Specifies that 2+n characters from the string are to be printed. 


If the backslashes are typed with no spaces, two characters are 
printed; if the backslashes are typed with one space, three 
characters are printed, and so on. 

If the string is longer than the field, the extra characters are 
ignored. If the field is longer than the string, the string is left- 
justified in the field and padded with spaces on the right. For 
example: 


10 AS="LOOK":BS="OUT" 

30 PRINT USING "!";AS;BS$ 

40 PRINT USING" \ \";AS;BS 

50 PRINT USING"\ \" FAST BS Plt" 
RUN 
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RUN 

LO 

OOKOUT 
LOOK OUT!! 


Specifies a variable length string field. When the field is 
specified with &, the string is output exactly as input. For 
example: 


10 A$="LOOK":BS="0UT" 
20 PRINT USING "!";AS$ 
30 PRINT USING "&";BS 
RUN 
LOUT 


Numeric Fields 


The following special characters may be used to format the numeric field: 


# 


A pound sign is used to represent each digit position. Digit 
positions are always filled. If the number to be printed has 
fewer digits than positions specified, the number is right- 
justified (preceded by spaces) in the field. 

A decimal point may be inserted at any position in the field. If 
the format string specifies that a digit is to precede the decimal 
point, the digit always is printed (as 0 if necessary). Numbers 
are rounded as necessary. For example: 


PRINT USING "##.##";.78 
0.78 
OK 


PRINT USING "###.##"; 987.654 
987.65 
OK 


PRINT USING "##.##" 710.2,5.3,66.789, .234 
10.20 5.30 66.79 0.23 


In the last example, three spaces were inserted at the end of the 
format string to separate the printed values on the line. 
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kk 


$$ 


#*S 


A plus sign at the beginning or end of the format string causes 
the sign of the number (plus or minus) to be printed before or 
after the number. 


A minus sign at the end of the format field causes negative 
numbers to be printed with a trailing minus sign. For example: 


PRINT USING"+##.##";-68.95,2.4,55.6,-9 
-68.95 +2.40 +55.60 -0.90 
OK 


PRINT USING"##.##-";-68.95,22.449,-7.01 
68.95 22.45 7.01 
OK 


A double asterisk at the beginning of the format string causes 
leading spaces in the numeric field to be filled with asterisks. 
The ** also specifies two more digit positions. For example: 


PRINT USING "**#.#";12.39,-0.9,765.1 
*12.4* -09765.1 
Ok 


A double dollar sign at the beginning of the format string causes 
a dollar sign to be printed to the immediate left of the formatted 
number. The $$ specifies two more digit positions, one of 
which is the dollar sign. The exponential format cannot be used 
with $$. Negative numbers cannot be used unless the minus 
sign trails to the right. For example: 


PRINT USING "SS###. ##"; 456.78 
$456.78 
Ok 


The **$ at the beginning of a format string combines the effects 
of the above two symbols. Leading spaces are filled with 
asterisks, and a dollar sign is printed before the number. **$ 
specifies three more digit positions, one of which is the dollar 
sign. For example: 


PRINT USING "**S##. ##"; 2.34 
***S2.34 
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A comma to the left of the decimal point in the format string 
causes a comma to be printed to the left of every third digit to 
the left of the decimal point. A comma at the end of the format 
string is printed as part of the string. 

PRINT USING "####.##";1234.5 

1234.50 

Ok 


Four carets may be placed after the digit position characters to 
specify exponential format. The four carets allow space for 
E+xx to be printed. Any decimal point position may be 
specified. The significant digits are left-justified, and the 
exponent is adjusted. Unless a leading + or trailing + or - is 
specified, one digit position is used to the left of the decimal 
point to print a space or a minus sign. For example: 


PRINT USING "##.##°°***"; 234.56 
2.35E+02 
Ok 


PRINT USING ".####^^^^-"; 888888 
Ok 


PRINT USING "+. ##**%*";123 
+.12E+03 
Ok 


Note that in the above examples the comma is not used as a 
delimiter with the exponential format. 

An underscore in the format string causes the next character to 
be output as a literal character. For example: 

PRINT USING "_ !##.##_=!";12.34 

112.34! 

Ok 


The literal character itself may be an underscore by placing 
in the format string. 
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% 


A percent sign is printed in front of the number if the number to 
be printed is larger than the specified numeric field. If rounding 
causes the number to exceed the field, a percent sign is printed 
in front of the rounded number. For example: 


PRINT USING "##.##";111.22 
$111.22 


PRINT USING ".##"'; .999 
%1.00 


If the number of digits specified exceeds 24, an "Ilegal 
function call" error results. 
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PRINT# and PRINT# USING Statements 
Purpose: 


To write data to a sequential disk file. 


Syntax: 


PRINT#file number, [USINGstring expressions, ]list of expressions 


Comments: 


file number is the number used when the file was opened for output. 


string expressions consists of the formatting characters described in the PRINT 
USING statement. 


list of expressions consists of the numeric and/or string expressions to be 
written to the file. 


Double quotation marks are used as delimiters for numeric and/or string 
expressions. The first double quotation mark opens the line for input; the 
second double quotation mark closes it. 


If numeric or string expressions are to be printed as they are input, they must be 
surrounded by double quotation marks. If the double quotation marks are 
omitted, the value assigned to the numeric or string expression is printed. If no 
value has been assigned, 0 is assumed. The double quotation marks do not 
appear on the screen. For example: 


10 PRINT#1,A 
0 


10 A=26 
20 PRINT#1,A 
26 


10 A=26 
20 PRINT#1, "A" 
A 
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If double quotation marks are required within a string, use CHR$(34)(the 
ASCII character for double quotation marks). For example: 


100 PRINT#1,"He said,"Hello", I think" 
He said, 0, I think 


because the machine assigns the value 0 the variable "Hello." 


100 PRINT#1, "He said, "CHRS$ (34) 
"Hello, "CHR$ (34) " I think." 
He said, "Hello," I think 


If the strings contain commas, semicolons, or significant leading blanks, 
surround them with double quotation marks. The following example will input 
"CAMERA" to A$, and "AUTOMATIC 93604-1" to B$: 


10 AS=""CAMERA, AUTOMATIC": BS="93604-1" 
20 PRINT#1,A$;BS$ 
30 INPUT#1,A$,BS$ 


To separate these strings properly, write successive double quotation marks 
using CHR§(34). For example: 

40 PRINT#1, CHRS$ (34) ; A$; CHRS$ (34) ; CHRS$ (34) ;B$; CHR$ (34) 
"CAMERA, AUTOMATIC""93604-1" 


The PRINT# statement may also be used with the USING option to control the 
format of the disk file. For example: 


PRINT#1, USING"SS###.##.";7 0; K;L 


PRINT# does not compress data on the diskette. An image of the data is written 
to the diskette, just as it would be displayed on the terminal screen with a 
PRINT statement. For this reason, be sure to delimit the data on the diskette so 
that it is input correctly from the diskette. 


In list of expressions, numeric expressions must be delimited by semicolons. 
For example: 
PRINT#1,A;B;C;X;Y;2Z 


If commas are used as delimiters, the extra blanks inserted between print fields 
will also be written to the diskette. Commas have no effect, however, if used 
with the exponential format. 
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String expressions must be separated by semicolons in the list. To format the 
string expressions correctly on the diskette, use explicit delimiters in list of 
expressions. For example, the following: 


10 AS$="CAMERA": BS="93604-1" 
20 PRINT#1,A$,B$ 


gives a diskette image of: 
CAMERA93604-1 


Because there are no delimiters, this would not be input as two separate strings. 
To correct the problem, insert explicit delimiters into the PRINT# statement as 
follows: follows: 


30 PRINT#1,AS;",";BS$ 


This gives the following diskette image, which can be read back into two string 
variables: 


CAMERA, 93604-1 
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PUT Statement (Files) 
Purpose: 


To write a record from a random buffer to a random disk file. 


Syntax: 


PUT[#]file number|[,record number) 


Comments: 


file number is the number under which the file was opened. 

record number is the number of the record. If it is omitted, the record has the 
next available record number (after the last PUT). 

The largest possible record number is 232 -1. This will allow you to have large 
files with short record lengths. The smallest possible record number is 1. 


The PRINT#, PRINT# USING, LSET, RSET, or WRITE# statements may be 
used to put characters in the random file buffer before a PUT statement. 


In the case of WRITE#, cw-nasic pads the buffer with spaces up to an enter. 
Any attempt to read or write past the end of the buffer causes a "Field 
overflow” error. 

PUT can be used for communications files. Here record number is the number 
of bytes written to the file. Record number must be less than or equal to the 
length of the buffer set in the OPEN "COM(n) statement. 
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PUT Statement (Graphics) 
Purpose: 


To transfer graphics images to the screen. 


Syntax: 


PUT(x,y),array,[,action verb] 


Comments: 


action verb may be PSET, PRESET, AND, OR, XOR. 

(x,y) are the coordinates of the top-left corner of the image to be transferred. 
The PUT and GET statements transfer graphics images to and from the screen. 
PUT and GET make possible animation and high-speed object motion in either 
graphics mode. 

The PUT statement transfers the image stored in the array onto the screen. The 
specified point is the coordinate of the upper-left comer of the image. An 
"Ilegal function call” error results if the image to be transferred is too large to 
fit onto the screen. 

The action verb is used to interact the transferred image with the image already 
on the screen. PSET transfers the data onto the screen verbatim. 

PRESET is the same as PSET except that an inverse image (black on white) is 
produced. 

AND transfers the image only if an image already exists under the transferred 
image. 

OR superimposes the image onto the existing image. 

XOR is a special mode often used for animation. XOR causes the points on the 
screen to be inverted where a point exists in the array image. This behavior is 
exactly like the cursor on the screen. 
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XOR is especially useful for animation. When an image is put against a 
complex background twice, the background is restored unchanged. An object 
can be moved around the screen without obliterating the background. 


The default action mode is XOR. 


For more information about effects within the different modes, see the 
COLOR, PALETTE, and SCREEN statements. 


Animation of an object is usually performed as follows: 
1. Put the object(s) on the screen. 
2. Recalculate the new position of the object(s). 


3. Put the object(s) on the screen a second time at the old location(s) to 
remove the old image(s). 


4. Return to Step 1, this time putting the object(s) at the new location. 


Movement done this way leaves the background unchanged. Flicker can be cut 
down by minimizing the time between Steps 4 and 1, and by making sure that 
there is enough time delay between Steps 1 and 3. If more than one object is 
being animated, process every object at once, one step at a time. 


If it is not important to preserve the background, animation can be performed 
using the PSET action verb. 


Leave a border around the image (when it is first gotten) as large or larger than 
the maximum distance the object will move. Thus, when an object is moved, 
this border effectively erases any points. This method may be somewhat faster 
than the method using XOR described above since only one PUT is required to 
move an object. However, the image to be PUT must be larger than the existing 
image. 


Examples: 


10 CLS:SCREEN 1 

20 PSET (130,120) 

30 DRAW "U25;E7;R20;D32;L6;012;L14" 

40 DRAW "D12;L6":PSET (137,102) 

50 DRAW "U4;E4;R8;D8;L12" 

60 PSET (137, 88) 

70 DRAW "E4;R20;D32;G4":PAINT (131,119) 
80 DIM A (500) 

90 GET (125,130)-(170,80),A 


100 
110 
120 
130 
140 
150 


FOR I= 1 TO 1000:NEXT I 
PUT (20,20),A,PSET 

FOR I= 1 TO 1000:NEXT i 
GET (125,130)-(170,80),A 
FOR I= 1 TO 1000:NEXT I 
PUT (220,130) ,A,PRESET 
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RANDOMIZE Statement 


Purpose: 


To reseed the random number generator. 


Syntax: 


RANDOMIZE [expression] 
RANDOMIZE TIMER 


Comments: 


If expression is omitted, Gw-BAsic suspends program execution and asks for a 
value by displaying the following line: 


Random number seed (-32768 to 32767)? 
If the random number generator is not reseeded, the RND function returns the 
same sequence of random numbers each time the program is run. 


To change the sequence of random numbers every time the program is run, 
place a RANDOMIZE statement at the beginning of the program, and change 
the argument with each run (see RND function). 


RANDOMIZE with no arguments will prompt you for a new seed. 
RANDOMIZE [expression] will not force floating-point values to integer. 
expression may be any numeric formula. 


To get anew random seed without prompting, use the new numeric TIMER 
function as follows: 


RANDOMIZE TIMER 
Example 1: 


The intemal clock can be set at intervals. 


10 RANDOMIZE TIMER 
20 FOR I=1 to 5 

30 PRINT RND; 

40 NEXT I 
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RUN 
-88598 .484668 .586328 .119426 .709225 
Ok 


RUN 
-803506 .162462 .929364 .292443 .322921 
Ok 


Example 2: 


The internal clock can be used for random number seed. 


5 N=VAL (MIDS (TIMES,7,2)) ‘get seconds for seed 
10 RANDOMIZE N ‘install number 
20 PRINT N ‘print seconds 
30 PRINT RND ‘print random number 
generated 
RUN 
36 
- 2466638 
Ok 
RUN 
37 
-6530511 
Ok 
RUN 
38 
5.943847E+02 
Ok 
RUN 
40 
- 8722131 
Ok 
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READ Statement 


Purpose: 


To read values from a DATA statement and assign them to variables. 


Syntax: 


READ list of variables 


Comments: 


A READ statement must always be used with a DATA statement. 


READ statements assign variables to DATA statement values on a one-to-one 
basis. 

READ statement variables may be numeric or string, and the values read must 
agree with the variable types specified. If they do not agree, a "Syntax" error 
tesults. 

A single READ statement may access one or more DATA statements. They are 
accessed in order. Several READ statements may access the same DATA 
statement. 

If the number of variables in list of variables exceeds the number of elements in 
the DATA statement(s), an "Out of data" message is printed. 

If the number of variables specified is fewer than the number of elements in the 
DATA statement(s), subsequent READ statements begin reading data at the 
first unread element. If there are no subsequent READ statements, the extra 
data is ignored. 

To reread DATA statements from the start, use the RESTORE statement. 
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Examples: 


80 FOR I=1 TO 10 

90 READ A(I) 

100 NEXT I 

110 DATA 3.08,5.19,3.12,3.98,4.24 
120 DATA 5.08,5.55,4.00,3.16,3.37 


This program segment reads the values from the DATA statements into array 
A. After execution, the value of A(1) is 3.08, and so on. The DATA statement 
(lines 110-120) may be placed anywhere in the program; they may even be 
placed ahead of the READ statement. 


5 PRINT 

10 PRINT "CITY", "STATE", "ZIP" 

20 READ C$,S$,2 

30 DATA "DENVER,", "COLORADO", 80211 
40 PRINT C$,S$,Z 

RUN 

CITY STATE ZIP 


DENVER, COLORADO 80211 
Ok 


This program reads string and numeric data from the DATA statement in line 
30. 
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REM Statement 
Purpose: 


To allow explanatory remarks to be inserted in a program. 


Syntax: 


REM[comment] 
[comment] 


Comments: 


REM statements are not executed, but are output exactly as entered when the 
program is listed. 


Once a REM or its abbreviation, an apostrophe (’), is encountered, the program 
ignores everything else until the next line number or program end is 
encountered. 

REM statements may be branched into from a GOTO or GOSUB statement, 
and execution continues with the first executable statement after the REM 
statement. However, the program runs faster if the branch is made to the first 
statement. 

Remarks may be added to the end of a line by preceding the remark with an 
apostrophe (’) instead of REM. 


Note Do not use REM in a DATA statement because it will be considered to 
be legal data. 
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Examples: 


120 REM CALCULATE AVERAGE VELOCITY 
130 FOR I=1 TO 20 

440 SUM=SUM+tV (I) 

450 NEXT I 


or 


129 FOR I=1 TO 20 ‘CALCULATED AVERAGE VELOCITY 
130 SUM=SUM+tV (I) 
140 NEXT I 
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RENUM Command 


Purpose: 


To renumber program lines. 


Syntax: 


RENUM|[new number],[old number][,incrementR]] 


Comments: 


new number is the first line number to be used in the new sequence. The default 
is 10. 

old number is the line in the current program where renumbering is to begin. 
The default is the first line of the program. 

increment is the increment to be used in the new sequence. The default is 10. 
RENUM also changes all line number references following ELSE, GOTO, 
GOSUB, THEN, ON...GOTO, ON...GOSUB, RESTORE, RESUME, and ERL 
statements to reflect the new line numbers. If a nonexistent line number appears 
after one of these statements, the error message, "Undefined line x in y" 
appears. The incorrect line number reference x is not changed by RENUM, but 
line number y may be changed. 


RENUM cannot be used to change the order of program lines (for example, 
RENUM 15,30 when the program has three lines numbered 10, 20 and 30) or to 
create line numbers greater than 65529. An "Illegal function call" error results. 


Examples: 


RENUM 


Renumbers the entire program. The first new line number will be 10. Lines 
increment by 10. 
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RENUM 300,,50 


Renumbers the entire program. The first new line number will be 300. Lines 
increment by 50. 


RENUM 1000, 900,20 


Renumbers the lines from 900 up so they start with line number 1000 and are 
incremented by 20. 
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RESET Command 


Purpose: 


To close all disk files and write the directory information to a diskette before it 
is removed from a disk drive. 


Syntax: 


RESET 


Comments: 


Always execute a RESET command before removing a diskette from a disk 
drive. Otherwise, when the diskette is used again, it will not have the current 
directory information written on the directory track. 

RESET closes all open files on all drives and writes the directory track to every 
diskette with open files. 
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RESTORE Statement 

Purpose: 

To allow DATA statements to be reread from a specified line. 
Syntax: 


RESTORE[line number] 


Comments: 


If line number is specified, the next READ statement accesses the first item in 
the specified DATA statement. 


If line number is omitted, the next READ statement accesses the first item in 
the first DATA statement. 


Examples: 


10 READ A,B,C, 
20 RESTORE 

30 READ D,E,F 

40 DATA 57,68,79 


Assigns the value 57 to both A and D variables, 68 to B and E, and so on. 
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RESUME Statement 
Purpose: 


To continue program execution after an error-recovery procedure has been 
performed. 


Syntax: 


RESUME 

RESUME 0 
RESUME NEXT 
RESUME line number 


Comments: 


Any one of the four formats shown above may be used, depending upon where 
execution is to resume: 


Syntax Result 

RESUME or RESUME 0 Execution resumes at the statement that 
caused an error. 

RESUME NEXT Execution resumes at the statement 
immediately following the one that caused 
an error. 

RESUME line number Execution resumes at the specified line 
number. 


A RESUME statement that is not in an error trapping routine causes a 
"RESUME without error" message to be printed. 
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Examples: 


10 ON ERROR GOTO 900 


900 IF (ERR=230) AND (ERL=90) THEN PRINT "TRY AGAIN": 
RESUME 80 


If an error occurs after line 10 is executed, the action indicated in line 900 is 
taken and the program continues at line 80. 
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RETURN Statement 


Purpose: 

To return from a subroutine. 
Syntax: 

RETURN [line number] 


Comments: 


The RETURN statement causes Gw-asic to branch back to the statement 
following the most recent GOSUB statement. A subroutine may contain more 
than one RETURN statement to retum from different points in the subroutine. 
Subroutines may appear anywhere in the program. 

RETURN line number is primarily intended for use with event trapping. It 


sends the event-trapping routine back into the Gw-sasic program at a fixed line 
number while still eliminating the GOSUB entry that the trap created. 


When a trap is made for a particular event, the trap automatically causes a 
STOP on that event so that recursive traps can never take place. The RETURN 
from the trap routine automatically does an ON unless an explicit OFF has been 
performed inside the trap routine. 


The nonlocal RETURN must be used with care. Any GOSUB, WHILE, or 
FOR statement active at the time of the trap remains active. 
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RIGHTS Function 


Purpose: 


To return the rightmost i characters of string x$. 


Syntax: 


RIGHT$(x$,i) 


Comments: 


If i is equal to or greater than LEN(x$), RIGHT$ returns x$. If i equals zero,the 
null string (length zero) is returned (see the MID$ and LEFT$ functions). 


Examples: 


10 A$="DISK BASIC" 
20 PRINT RIGHTS (AS, 5) 
RUN 

BASIC 

Ok 


Prints the rightmost five characters in the A$ string. 
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RMDIR Command 


Purpose: 


To delete a subdirectory. 


Syntax: 


RMDIR pathname 


Comments: 


pathname is a string expression, not exceeding 63 characters, identifying the 
subdirectory to be removed from its parent. 


The subdirectory to be deleted must be empty of all files except "." and ".." or a 
"Path file/access" error is given. 


Examples: 


Referring to the sample directory structure illustrated in CHDIR, the following 
command deletes the subdirectory report: 


RMDIR "SALES\JOHN\REPORT" 
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RND Function 


Purpose: 


To return a random number between 0 and 1. 


Syntax: 


RND[(x)] 


Comments: 


The same sequence of random numbers is generated each time the program is 
run unless the random number generator is reseeded (see RANDOMIZE 
statement). If x is equal to zero, then the last number is repeated. 

If x is greater than 0, or if x is omitted, the next random number in the sequence 
is generated. 


To get a random number within the range of zero through n, use the following 
formula: 


INT(RND*(n+1)) 


The random number generator may be seeded by using a negative value for x. 


Examples: 


10 FOR I=1 TO 5 

20 PRINT INT (RND*101); 
30 NEXT 

RUN 

53 30 31 51 5 

Ok 


Generates five pseudo-random numbers within the range of 0-100. 
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RUN Command 
Purpose: 


To execute the program currently in memory,or to load a file from the diskette 
into memory and run it. 


Syntax: 


RUN [line number]{,r] 
RUN filename[,r] 


Comments: 


RUN or RUN line number runs the program currently in memory. 


If line number is specified, execution begins on that line. Otherwise, execution 
begins at the lower line number. 


If there is no program in memory when RUN is executed, Gw-BAsic returns to 
command level. 


RUN filename closes all open files and deletes the current memory contents 
before loading the specified file from disk into memory and executing it. 


The r option keeps all data files open. 


If you are using the speaker on the computer, please note that executing the 
RUN command will turn off any sound that is currently running and will reset 
to Music Foreground. Also, the PEN and STRIG statements are reset to OFF. 


Examples: 


RUN NEWFIL,R 
Runs NEWFIL without closing data files. 
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SAVE Command 
Purpose: 


To save a program file on diskette. 


Syntax: 


SAVE filename,{,a] 
SAVE filename,[,p] 


Comments: 


filename is a quoted string that follows the normal MS-DOS naming 
conventions. If filename already exists, the file will be written over. If the 
extension is omitted, .bas will be used. 


The a option saves the file in ascıı format. Otherwise, Gw-Basic saves the file in 
a compressed binary format. ascu format takes more space on the diskette, but 
some diskette access commands (for example, the MERGE command and some 
Ms-Dos commands, such as TYPE) may require an asci format file. 


The p option protects the file by saving it in an encoded binary format. When a 
protected file is later run or loaded, any attempt to list or edit it fails. When the 
p option is used, make an additional copy under another name or diskette to 
facilitate future program maintenance. 


Examples: 


The following command saves the file com2.bas in the ascu format: 
SAVE COM2,A 


The following command saves the file prog.bas in binary format, and protects 
access: 


SAVE PROG, P 


218 GW-BASIC User's Reference 


SCREEN Function 


Purpose: 


To return the ascu code (0-255) for the character at the specified row (line) and 
column on the screen. 


Syntax: 


x=SCREEN(row,col[,z]}) 

Comments: 

x is a numeric variable receiving the ascn code returned. 
row is a valid numeric expression within the range 1 to 25. 


col is a valid numeric expression 1 to 40, or 1 to 80, depending upon screen 
width setting. See the WIDTH statement. 


z is a valid numeric expression with a true or false value. It may be used only in 
alpha mode. 


The ordinal of the character at the specified coordinates is stored in the numeric 
variable. In alpha mode, if the optional parameter z is given and is true 
(nonzero), the color attribute for the character is returned instead of the ascu 
code for the character (see the COLOR statement). 


Any values entered outside of the range indicated result in an “Illegal function 
call" error. Row 25 may be referenced only if the function key is off. 


Examples: 


100 X=SCREEN (10,10) 
If the character at 10,10 is A, then X is 65. 
110 X= SCREEN (1,1,1) 


Returns the color attribute of the character in the upper-left comer of the 
screen. 
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SCREEN Statement 
Purpose: 


To set the specifications for the display screen. 


Syntax: 


SCREEN [mode] [,[colorswitch]][,[apage}][,[vpage]] 


Comments: 


The SCREEN statement is chiefly used to select a screen mode appropriate for 
a particular display-hardware configuration. Supported hardware configurations 
and screen modes are described below. 


MDPA with Monochrome Display: Mode 0 


The IBM Monochrome Display and Printer Adapter (MDPA) is used to 
connect only to a monochrome display. Programs written for this configuration 
must be text mode only. 


CGA with Color Display: Modes 0, 1, and 2 


The IBM Color Graphics Adapter (CGA) and Color Display are typically 
paired with each other. This hardware configuration permits the running of text 
mode programs, and both medium-resolution and high-resolution graphics 
programs. 


EGA with Color Display: Modes 0, 1, 2, 7, and 8 


The five screen modes 0, 1, 2, 7, and 8 allow you to interface to the IBM Color 
Display when it is connected to an IBM Enhanced Graphics Adapter (EGA). If 
EGA switches are set for CGA compatibility, programs written for modes 1 
and 2 will run just as they would with the CGA. Modes 7 and 8 are similar to 
modes 1 and 2, except that a wider range of colors is available in modes 7 and 
8. 
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EGA with Enhanced Color Display: Modes 0, 1, 2, 7, and 8 

With the EGA/IBM Enhanced Display configuration, modes 0, 1, 2, 7, and 8 

are virtually identical to their EGA/Color Display counterparts. Two possible 

differences are as follows: 

1. In mode 0, the border color cannot be the same as for the EGA/Color 
Display because the border cannot be set on an Enhanced Color Display 
when it is in 640 x 350 text mode. 

2. The quality of the text is better on the Enhanced Color Display (an 8 x 14 
character box for Enhanced Color Display versus an 8 x 8 character box 
for color display). 


EGA with Enhanced Color Display: Mode 9 


The full capability of the Enhanced Color Display is taken advantage of in this 
mode. Mode 9 allows the highest resolution possible for the EGA/Enhanced 
Color Display configuration. Programs written for this mode will not work for 
any other hardware configuration. 


EGA with Monochrome Display: Mode 10 


The IBM Monochrome Display can be used to display monochrome graphics at 
a very high resolution in this mode. Programs written for this mode will not 
work for any other hardware configuration. 


Arguments 


The mode argument is an integer expression with legal values 0, 1, 2, 7, 8, 9, 
and 10. All other values are illegal. Selection of a mode argument depends 
primarily on your program’s anticipated display hardware, as described above. 
Each of the SCREEN modes is described individually in the following 
paragraphs. 
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SCREEN 0 


Text mode only 


Either 40 x 25 or 80 x 25 text format with character-box size of 8 x 8 (8 x 
14 with EGA) 


Assignment of 16 colors to any of 2 attributes 
Assignment of 16 colors to any of 16 attributes (with EGA) 


SCREEN 1 


320 x 200 pixel medium-resolution graphics 

80 x 25 text format with character-box size of 8 x 8 
Assignment of 16 colors to any of 4 attributes 
Supports both EGA and CGA 

2 bits per pixel 


SCREEN 2 


640 x 200 pixel high-resolution graphics 

40 x 25 text format with character-box size of 8 x 8 
Assignment of 16 colors to any of 2 attributes 
Supports both EGA and CGA 

1 bit per pixel 


SCREEN 7 


320 x 200 pixel medium-resolution graphics 
40 x 25 text format with character-box size of 8 x 8 


2, 4, or 8 memory pages with 64K, 128K, or 256K of memory, 
respectively, installed on the EGA 


Assignment of any of 16 colors to 16 attributes 
EGA required 
4 bit per pixel 


222 GW-BASIC User’s Reference 


SCREEN 8 


640 x 200 pixel high-resolution graphics 
80 x 25 text format with character-box size of 8 x 8 


1, 2, or 4 memory pages with 64K, 128K, or 256K of memory, 
respectively, installed on the EGA 


Assignment of any of 16 colors to 16 attributes 
EGA required 
4 bits per pixel 


SCREEN 9 


640 x 350 pixel enhanced-resolution graphics 
80x25 text format with character-box size of 8 x 14 


Assignment of either 64 colors to 16 attributes (more than 64K of EGA 
memory), or 16 colors to 4 attributes (64K of EGA memory) 


Two display pages if 256K of EGA memory installed 
EGA required 


2 bits per pixel (64K EGA memory) 
4 bits per pixel (more than 64K EGA memory) 


SCREEN 10 


640 x 350 enhanced-resolution graphics 

80 x 25 text format with character-box size of 8 x 14 
Two display pages if 256K of EGA memory installed 
Assignment of up to 9 pseudo-colors to 4 attributes 
EGA required 

2 bits per pixel 
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The following are default attributes for SCREEN 10, monochrome display: 


Attribute Value Displayed Pseudo-Color 
0 Off 

1 On, normal intensity 

2 Blink 

3 On, high intensity 


The following are color values for SCREEN 10, monochrome display: 


Color Value Displayed Pseudo-Color 
0 Off 

1 Blink, off to on 

2 Blink, off to high intensity 
3 Blink, on to off 

4 On 

5 Blink, on to high intensity 
6 Blink, high intensity to off 
7 Blink, high intensity to on 
8 High intensity 


For both composite monitors and TVs, the colorswitch is a numeric expression 
that is either true (nonzero) or false (zero). A value of zero disables color and 
permits display of black and white images only. A nonzero value permits color. 
The meaning of the colorswitch argument is inverted in SCREEN mode 0. 


For hardware configurations that include an EGA and enough memory to 
support multiple-screen pages, two arguments are available. These apage and 
vpage arguments determine the "active" and "visual" memory pages. The active 
page is the area in memory where graphics statements are written; the visual 
page is 

the area of memory that is displayed on the screen. 


Animation can be achieved by alternating the display of graphics pages. The 
goal is to display the visual page with completed graphics output, while 
executing graphics statements in one or more active pages. A page is displayed 
only when graphics output to that page is complete. Thus, the following 
program fragment is typical: 


224 GW-BASIC User’s Reference 


SCREEN 7,,1,2 ‘work in page 1, show page 2 


Graphics output to page I 
while viewing page 2 


SCREEN 7,,2,1 '’work in page 2, show page 
1 


Graphics output to page 2 
while viewing page I 


The number of pages available depends on the SCREEN mode and the amount 
of available memory, as described in the following table: 


Table 2 
SCREEN Mode Specifications 
Attribute Color EGA Page 
Mode Resolution Range Range Memory Pages Size 
0 40-column text NA 0-15a NA 1 2K 
80-column text NA 0-152 NA 1 4K 
1 320 x 200 0-3b 0-3 NA 1 16K 
2 640 x 200 0-1b 0-1 NA 1 16K 
7 320 x 200 0-15 0-15 64K 2 32K 
128K 4 
256K 8 
8 640 x 200 0-15 0-15 64K 1 64K 
128K 2 
256K 4 
9 640 x 350 0-3 0-15 64K 1 64K 
0-15 0-63 128K 1 128K 
0-15 0-63 256K 2 
10 640 x 350 0-3 0-8 128K 1 128K 
256K 2 


aNumbers in the range 16-31 are blinking versions of the colors 0-15. 
bAttributes applicable only with EGA. 
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Attributes and Colors 


For various screen modes and display hardware configurations, different 
attribute and color settings exist. (See the PALETTE statement for a discussion 
of attribute and color number.) The majority of these attribute and color 


configurations are summarized in the following table: 


Table 3 
Default Attributes and Colors for Most Screen Modes 
Attributes for Mode Color Display Monochrome Display 
1,92 0,7,8,9> Numbere Color Numbert Color 
00 0 0 Black 0 Off 
1 1 Blue (Underlined)@ 
2 2 Green 1 Ona 
3 3 Cyan 1 Ona 
4 4 Red 1 Ona 
5 5 Magenta 1 Ona 
6 6 Brown 1 Ona 
7 7 White 1 Ona 
8 8 Gray 0 off 
9 9 Light Blue High intensity 
(underlined) 
10 10 Light Green 2 High intensity 
1 11 11 Light Cyan 2 High intensity 
12 12 Light Red 2 High intensity 
2 13 13 Light Magenta 2 High intensity 
14 14 Yellow 2 High intensity 
3 1 15 15 High-intensity 0 Off 
White 
4Off when used for background. 
bWith EGA memory > 64K. 


COnly for mode 0 monochrome. 
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The default foreground colors for the various modes are given in the following 
table: 


Table 4 
Default Foreground Colors 


Default foreground attribute Default foreground color 
Screen Color/Extended® Monochrome  Color/Extended4a Monochrome 
mode Display Display Display Display 
0 7 7 7 1 
1 3 NA 15 NA 
2 1 NA 15 NA 
7 15 NA 15 NA 
8 15 NA 15 NA 
9 3b NA 63 NA 
10 NA 3 NA 8 


aIBM Enhanced Color Display 
b15 if greater than 64K of EGA memory 
NA=Not Applicable 
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SGN Function 


Purpose: 


To return the sign of x. 


Syntax: 


SGN(x) 
Comments: 


x is any numeric expression. 

If x is positive, SGN(x) returns 1. 
If x is 0, SGN(x) returns 0. 

If x is negative, SGN(x) returns -1. 


This statement is similar to, but not the same as SIN(x), which returns a 
trigonometric function in radians, rather than in ones and zeros. 


Examples: 


10 INPUT "Enter value",x 
20 ON SGN(X)+2 GOTO 100,200,300 


cw-Basic branches to 100 if X is negative, 200 if X is 0, and 300 if X is positive. 
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SHELL Statement 
Purpose: 


To load and execute another program or batch file. When the program finishes, 
control returns to the Gw-BAsic program at the statement following the SHELL 
statement. A program executed under control of cw-nasic is referred to as a 
child process. 


Syntax: 


SHELL [string] 


Comments: 


String is a valid string expression containing the name of a program to run and 
(optionally) command arguments. 


The program name in string may have any extension that MS-DOS 
COMMAND.COM supports. If no extension is supplied, COMMAND will 
look for a .COM file, then an .EXE file, and finally, a .BAT file. If none is 
found, SHELL will issue a "File not found” error. 


Any text separated from the program name by at least one blank space will be 
processed by COMMAND as program parameters. 


GW-BASIC remains in memory while the child process is running. When the child 
process finishes, GW-BASIC continues at the statement following the SHELL 
statement. 


SHELL with no string will go to MS-DOS. You may now do anything that 
COMMAND allows. When ready to return to Gw-nasic, type the MS-DOS 
command EXIT. 


Examples: 


SHELL 
A>DIR 
A>EXIT 
Ok 
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Write some data to be sorted, use SHELL SORT to sort it, then read the sorted 
data to write a report. 


10 OPEN "SORTIN.DAT" FOR OUTPUT AS #1 
20 ‘write data to be sorted 


1000 CLOSE 1 

1010 SHELL "SORT <SORTIN.DAT>SORTOUT. DAT" 
1020 OPEN "“SORTOUT.DAT" FOR INPUT AS #1 
1030 ‘Process the sorted data 


230 GW-BASIC User's Reference 


SIN Function 
Purpose: 


To calculate the trigonometric sine of x, in radians. 


Syntax: 


SIN(x) 


Comments: 


SIN(x) is calculated in single-precision unless the /d switch is used when cw- 
BASIC is executed. 


To obtain SIN(x) when x is in degrees, use SIN(x*1/180). 
Examples: 
PRINT SIN(1.5) 


-9974951 
Ok 


The sine of 1.5 radians is .9974951 (single-precision). 
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SOUND Statement 
Purpose: 


To generate sound through the speaker. 


Syntax: 


SOUND freq,duration 


Comments: 


freq is the desired frequency in Hertz (cycles per second). freq is a numeric 
expression within the range of 37 to 32767. 


duration is the desired duration in clock ticks. Clock ticks occur 18.2 times per 
second. duration must be a numeric expression within the range of 0 to 65535. 


Values below .022 produce an infinite sound until the next SOUND or PLAY 
statement is executed. 


If duration is zero, any active SOUND statement is turned off. If no SOUND 
statement is running, a duration of zero has no effect. 


The sound is executed in foreground or background depending on the PLAY 
statement. 


Examples: 


The following example creates random sounds of short duration: 


2500 SOUND RND*1000+37,2 
2600 GOTO 2500 
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The following table shows the relationship of notes and their frequencies in the 
two octaves adjacent to middle C. 


Table 5 
Relationships of Notes and Frequencies 


Note Frequency Note Frequency 
C 130.810 ce 523.250 
D 146.830 D 587.330 
E 164.810 E 659.260 
F 174.610 F 698.460 
G 196.000 G 783.990 
A 220.000 A 880.000 
B 246.940 B 987.770 
C 261.630 C 1046.500 
D 293.660 D 1174.700 
E 329.630 E 1318.500 
F 349.230 F 1396.900 
G 392.000 G 1568.000 
A 440.000 A 1760.000 
B 493.880 B 1975.500 
*Middle C. 


By doubling or halving the frequency, the coinciding note values can be 
estimated for the preceding and following octaves. 


To produce periods of silence, use the following statement: 
SOUND 32767, duration 


To calculate the duration of one beat, divide beats per minute into the number 
of clock ticks in a minute (1092). 
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The following table illustrates tempos requested by clock ticks: 


Table 6 
Tempos Requested by Clock Ticks 
Beats/ Ticks/ 

Tempo Notation Minute Beat 
very slow Larghissimo 

Largo 40-66 27.3-18.2 

Larghetto 60-66 18.2-16.55 

Grave 

Lento 

Adagio 66-76 16.55-14.37 
slow Adagietto 

Andante 76-108 14.37-10.11 
medium Andantino 

Moderato 108-120 10.11-9.1 
fast Allegretto 

Allegro 120-168 9.1-6.5 

Vivace 

Veloce 

Presto 168-208 6.5-5.25 


very fast Prestissimo 
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SPACES Function 


Purpose: 


To return a string of x spaces. 


Syntax: 


SPACE$(x) 


Comments: 


x is rounded to an integer and must be within the range of 0 to 255 (see the SPC 
function). 


Examples: 


10 FOR N=1 TO 5 
20 X$=SPACES (N) 
30 PRINT X$;N 
40 NEXT N 
RUN 
1 
2 
3 

4 

5 
Ok 


Line 20 adds one space for each loop execution. 
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SPC Function 


Purpose: 


To skip a specified number of spaces in a PRINT or an LPRINT statement. 


Syntax: 


SPC(n) 


Comments: 


n must be within the range of 0 to 255. 


If n is greater than the defined width of the printer or the screen, the value used 
will be n MOD width. 


A semicolon is assumed to follow the SPC(n) command. 


SPC may only be used with PRINT, LPRINT and PRINT# statements (see the 
SPACES function). 


Examples: 


PRINT "OVER" SPC(15) "THERE" 
OVER THERE 
Ok 
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SQR Function 
Purpose: 


Returns the square root of x. 
Syntax: 

SQR(x) 

Comments: 


x must be greater than or equal to 0. 


SQR(x) is computed in single-precision unless the /d switch is used when GW- 
BASIC is executed. 


Examples: 


10 FOR X=10 TO 25 STEP 5 
20 PRINT X; SQR(X) 


30 NEXT 

RUN 

10 3.162278 
15 3.872984 
20 4.472136 
25 5 


Ok 
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STICK Function 

Purpose: 

To return the x and y coordinates of two joysticks. 
Syntax: 

x=STICK(n) 

Comments: 


x is anumeric variable for storing the result. 
nis a valid numeric expression within the range of 0 to 3. 


Value of n Coordinate Returned 

0 x coordinate of joystick A. Stores the x and y values for 
both joysticks for the following three function calls. 

1 y coordinate of joystick A. 
x coordinate of joystick B. 


3 y coordinate of joystick B. 
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STOP Statement 


Purpose: 


To terminate program execution and return to command level. 


Syntax: 


STOP 


Comments: 


STOP statements may be used anywhere in a program to terminate execution. 
When a STOP is encountered, the following message is printed: 


Break in line nnnnn 


Unlike the END statement, the STOP statement does not close files. 


Gw-BASIC always returns to command level after a STOP is executed. Execution 
is resumed by issuing a CONT command. 


Examples: 


10 INPUT A,B,C 

20 K=A%2*5.3:L=B%3/.26 
30 STOP 

40 M=C*K+100:PRINT M 
RUN 

?1,2,3 

BREAK IN 30 

Ok 

PRINT L 

30.76923 

Ok 

CONT 

115.9 

Ok 
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STR$ Function 
Purpose: 


To return a string representation of the value of x. 


Syntax: 


STR$(x) 


Comments: 


STR$(x) is the complementary function to VAL(x$) (see the VAL function). 


Examples: 


5 REM ARITHMETIC FOR KIDS 
10 INPUT "TYPE A NUMBER";N 
20 ON LEN(STRS$(N)) GOSUB 30,40,50 


This program branches to various subroutines, depending on the number of 
characters typed before the RETURN key is pressed. 
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STRIG Statement and Function 
Purpose: 


To return the status of the joystick triggers. 


Syntax: 


As a statement: 
STRIG ON 
STRIG OFF 
As a function: 
x=STRIG(n) 


Comments: 


x is a numeric variable for storing the result. 

nis a valid numeric expression within the range of 0 to 7. 

STRIG ON must be executed before any STRIG(”) function calls may be 
made. Once STRIG ON is executed, cw-Basic will check to see if a button has 
been pressed before every statement is executed. STRIG OFF disables the 
checking. 

n is a numeric expression within the range of 0 to 7 that returns the following 
values: 


Value of n Returns 

0 -1 if trigger Al was pressed since the last STRIG(0) 
statement; returns 0, if not. 

1 -1 if trigger A1 is currently pressed; returns 0, if not. 

2 -1 if trigger B1 was pressed since the last STRIG(2) 


statement; returns 0, if not. 
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-1 if trigger B1 is currently pressed; returns 0, if not. 


-1 if trigger A2 was pressed since the last STRIG(4) 
statement; returns 0 if not. 


-1 if trigger A2 is currently pressed; returns 0, if not. 
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STRIG(n) Statement 


Purpose: 


To allow the use of a joystick by enabling or disabling the trapping of its 
buttons. 


Syntax: 


STRIG(n) ON 
STRIG(n) OFF 
STRIG(n) STOP 


Comments: 


nis 0, 2, 4, or 6, corresponding to the buttons on the joystick, where 


0 is button Al 
2 is button B1 
4 is button A2 
6 is button B2 


Examples: 


STRIG(n) ON 


Enables trapping of the joystick buttons. After this statement is executed, Gw- 
Basic checks to see if this button has been pressed before executing following 
statements. 


STRIG(n) OFF 


Disables cw-Basic from checking the state of the button. 


STRIG(n) STOP 


Disables trapping of a given button through the ON STRIG() statement. But, 
any pressings are remembered so that trapping may take place once it is 
reenabled. 
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STRING$ Function 


Purpose: 


To return 
e —_astring of length n whose characters all have ascu code j, or 
e the first character of x$ 


Syntax: 


STRING$(n,/) 
STRING$(n,x3) 


Comments: 


STRINGS is also useful for printing top and bottom borders on the screen or 
the printer. 


n and j are integer expressions in the range 0 to 255. 
Examples: 
10 X$ = STRINGS (10, 45) 


20 PRINT X$ "MONTHLY REPORT" X$ 
RUN 


45 is the decimal equivalent of the ASCII symbol for the minus (-) sign. 
Appendix C in the GW-BASIC User's Guide lists ascii character codes. 
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SWAP Statement 
Purpose: 


To exchange the values of two variables. 


Syntax: 


SWAP variable! ,variable2 


Comments: 


Any type variable may be swapped (integer, single-precision, double-precision, 
string), but the two variables must be of the same type or a "Type mismatch" 
error results. 


Examples: 


LIST 
10 AS="ONE ":BS$="ALL ":CS="FOR " 
20 PRINT AS C$ B$ 

30 SWAP AS, BS 

40 PRINT A$ C$ B$ 

RUN 

Ok 

ONE FOR ALL 

ALL FOR ONE 

Ok 


Line 30 swaps the values in the A$ and B$ strings. 
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SYSTEM Command 


Purpose: 


To return to MS-Dos. 


Syntax: as 


SYSTEM 


Comments: 


Save your program before pressing RETURN, or the program will be lost. 


The SYSTEM command closes all the files before it returns to ms-pos. If you 
entered cw-sasic through a batch file from Ms-pos, the SYSTEM command 
returns you to the batch file, which continues executing at the point it left off. 


Examples: 


SYSTEM 
A> 
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TAB Function 


Purpose: 


Spaces to position n on the screen. 


Syntax: 


TAB(n) 


Comments: 


If the current print position is already beyond space n, TAB goes to that 
position on the next line. 


Space 1 is the leftmost position. The rightmost position is the screen width. 

n must be within the range of 1 to 255. 

If the TAB function is at the end of a list of data items, cw-Basic will not retum 
the cursor to the next line. It is as though the TAB function has an implied 
semicolon after it. 


TAB may be used only in PRINT, LPRINT, or PRINT# statements (see the 
SPC function). 


Examples: 


10 PRINT "NAME" TAB(25) "AMOUNT": PRINT 
20 READ AS,B$ 

30 PRINT A$ TAB(25) B$ 

40 DATA "G. T. JONES","$25.00" 


RUN 
NAME AMOUNT 
G. T. JONES $25.00 


Ok 


TAN Function 247 


TAN Function 
Purpose: 


To calculate the trigonometric tangent of x, in radians. 


Syntax: 


TAN(x) 


Comments: 


TAN(2) is calculated in single-precision unless the /d switch is used when cw- 
BASIC is executed. 


If TAN overflows, the "Overflow" error message is displayed; machine infinity 
with the appropriate sign is supplied as the result, and execution continues. 


To obtain TAN(x) when x is in degrees, use TAN(x*1/180). 


Examples: 


10 Y = TAN (X) 


When executed, Y will contain the value of the tangent of X radians. 
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TIMES Statement and Variable 
Purpose: 


To set or retrieve the current time. 
Syntax: 


As a statement: 
TIMES = string exp 
As a variable: 

string exp=TIME$ 


Comments: 


string exp is a valid string literal or variable that lets you set hours (hh), hours 
and minutes (hh:mm), or hours, minutes, and seconds (hh:mm:ss). 


hh sets the hour (0-23). Minutes and seconds default to 00. 
hh:mm sets the hour and minutes (0-59). Seconds default to 00. 
hh:mm:ss sets the hour, minutes, and seconds (0-59). 

If string exp is not a valid string, a "Type mismatch” error results. 


As you enter any of the above values, you may omit the leading zero, if any. 
You must, however, enter at least one digit. If you wanted to set the time as a 
half hour after midnight, you could enter TIME$= "0:30", but not TIME$= 
":30". 

If any of the values are out of range, an "Illegal function call" error is issued. 
The previous time is retained. 


The current time is stored if TIMES is the target of a string assignment. 
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The current time is fetched and assigned to the string variable if TIMES is the 
expression in a LET or PRINT statement. 


If string exp = TIMES, TIMES returns an 8-character string in the form 
hh:mm:ss. 


Examples: 


The following example sets the time at 8:00 A.M.: 


TIMES = "08:00" 
Ok 

PRINT TIMES 
08:00:05 

Ok 


The following program displays the current date and time on the 25th line of 
the screen and will sound on the minute and half minute. 


10 KEY OFF:SCREEN O:WIDTH 80:CLS 

20 LOCATE 25,5 

30 PRINT DATES, TIMES; 

40 SEC=VAL (MIDS (TIME$,7,2)) 

50 IF SEC=SSEC THEN 20 ELSE SSEC=SEC 
60 IF SEC=0 THEN 1010 

70 IF SEC=30 THEN 1020 

80 IF SEC<57 THEN 20 


1000 SOUND 1000,2:GOTO 20 
1010 SOUND 2000,8:GOTO 20 
1020 SOUND 400,4:GOTO 20 
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TIMER Function 
Purpose: 


To return single-precision floating-point numbers representing the elapsed 
number of seconds since midnight or system reset. 


Syntax: 
v=TIMER 


Comments: 


Fractions of seconds are calculated to the nearest degree possible. Timer is 
read-only. 
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TRON/TROFF Commands 


Purpose: 


To trace the execution of program statements. 


Syntax: 


TRON 
TROFF 


Comments: 


As an aid in debugging, the TRON (trace on) command enables a trace flag that 
prints each line number of the program as it is executed. The numbers appear 
enclosed in square brackets. 


TRON may be executed in either the direct or indirect mode. 


The trace flag is disabled with the TROFF (trace off) command, or when a 
NEW command is executed. 


Examples: 


TRON 

Ok 

10 K=10 

20 FOR J=1 TO 2 

30 L=K + 10 

40 PRINT J;K;L 

50 K=K+10 

60 NEXT 

70 END 

RUN 

[10] [20] [30] [40] 1 10 20 
[50] [60] [30] [40] 2 20 30 
[50] [60] [70] 

Ok 

TROFF 

Ok 
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UNLOCK Statement 


Purpose: 


To release locks that have been applied to an opened file. This is used in a 
multi-device environment, often referred to as a network or network 
environment. 


Syntax: 
UNLOCK [#]n [,[record number] [TO record number)] 


Comments 


nis the number that was assigned the file as it was originally numbered in the 
program. 


record number is the number of the individual record that is to be unlocked. Or, 
if a range of records are to be unlocked, record number designates the 
beginning and ending record of the specified range. 


The range of legal record numbers is 1 to 2 32 -1. The limit on record size is 
32767 bytes. 


The record range specified must be from lower to (the same or) higher record 
numbers. 


If a starting record number is not specified, the record number 1 is assumed. 


If an ending record number is not specified, then only the specified record is 
unlocked. 


The following are legal UNLOCK statements: 


UNLOCK #n unlocks the entire file n 
UNLOCK #n, X unlocks record X only 
UNLOCK #n,TO Y unlocks records 1 through Y 


UNLOCK #n, X TO Y unlocks records X through Y 
The locked file or record range should be unlocked before the file is closed. 
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Failure to execute the UNLOCK statement can jeopardize future access to that 
file in a network environment. 


In the case of files opened in random mode, if a range of record numbers is 
specified, this range must match exactly the record number range given in the 
LOCK statement. 


The "Permission denied" message will appear if a syntactically correct 
UNLOCK request cannot be granted. The UNLOCK statement must match 
exactly the paired LOCK statement. 


It is expected that the time in which files or regions within files are locked will 
be short, and thus the suggested usage of the LOCK statement is within 
shortterm paired LOCK/UNLOCK statements. 


Examples: 


The following demonstrates how the LOCK/UNLOCK statements should be 
used: 


LOCK #1, 1 TO 4 
LOCK #1, 5 TO 8 
UNLOCK #1, 1 TO 4 
UNLOCK #1, 5 TO 8 


The following example is illegal: 


LOCK #1, 1 TO 4 
LOCK #1, 5 TO 8 
UNLOCK #1, 1 TO 8 
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USR Function 


Purpose: 


To call an assembly language subroutine. 


Syntax: 


v=USR[n](argument) 


Comments: 


n specifies which USR routine is being called. 

argument can be any numeric or string expression. 

Although the CALL statement is recommended for calling assembly language 
subroutines, the USR function call may also be used. See Appendix D in the 
GW-BASIC User's Guide for a comparison of CALL and USR and for a 
detailed discussion of calling assembly language subroutines. 

Only values 0-9 are valid for n. If n is omitted, USRO is assumed (see DEF 
USR for the rules governing n). 

If a segment other than the default segment (cw-sasic data segment, DS) is 
used, a DEF SEG statement must be executed prior to a USR call. This ensures 
that the code segment points to the subroutine being called. 

The segment address given in the DEF SEG statement determines the starting 
segment of the subroutine. 

For each USR function, a corresponding DEF USR statement must have been 
executed to define the USR call offset. This offset and the currently active DEF 
SEG segment address determine the starting address of the subroutine. 


If more than 10 user routines are required, the value(s) of DEF USR may be 
redefined for the other starting addresses as many times as needed. 
The type (numeric or string) of the variable receiving the function call must be 


consistent with the argument passed. If no argument is required by the 
assembly language routine, then a dummy argument must be supplied. 
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VAL Function 


Purpose: 


Returns the numerical value of string x$. 


Syntax: 


VAL(x$) 


Comments: 


The VAL function also strips leading blanks, tabs, and line feeds from the 
argument string. For example, the following line returns -3: 


VAL(" -3") 

The STR$ function (for numeric to string conversion) is the complement to the 
VAL(x$) function. 

If the first character of x$ is not numeric, the VAL(x$) will return zero. 


Examples: 


10 READ NAMES,CITY$,STATES, ZIP$ 

20 IF VAL (ZIP$)<90000 OR VAL(ZIP$)>96699 
THEN PRINT NAMES TAB(25) "OUT OF STATE" 

30 IF VAL(ZIP$)>=90801 AND VAL (ZIP$)<=90815 
THEN PRINT NAMES TAB(25) "LONG BEACH" 
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VARPTR Function 
Purpose: 


To return the address in memory of the variable or file control block (FCB). 


Syntax: 


VARPTR(variable name) 
VARPTR(#/file number) 


Comments: 


VARPTR is usually used to obtain the address of a variable or array so it can be 
passed to an assembly language subroutine. A function call of the following 
form: 


VARPTR (A (0) ) 


is usually specified when passing an array, so that the lowest-addressed element 
of the array is returned. 

All simple variables should be assigned before calling VARPTR for an array, 
because the addresses of the arrays change whenever a new simple variable is 
assigned. 

VARPTR (#file number) retums the starting address of the cw-Basic File 
Control Block assigned to file number. 

VARPTR (variable name) returns the address of the first byte of data identified 
with the variable name. 

A value must be assigned to variable name prior to execution of VARPTR, 
otherwise, an "Illegal function call" error results. 

Any type variable name may be used (numeric, string, or array), and the 
address returned will be an integer within the range of 32767 to -32768. If a 
negative address is returned, it is added to 65536 to obtain the actual address. 
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Offsets to information in the FCB from the address returned by VARPTR are 
shown in the following table: 


Table 7 

Offsets to FCB Information 
Offset Length Name 

0 1 Mode 

1 38 FCB 

39 2 CURLOC 
41 1 ORNOFS 
42 1 NMLOFS 
43 3 we 

46 DEVICE 
47 1 WIDTH 
48 1 POS 

49 1 FLAGS 
50 1 OUTPOS 


Description 
The mode in which the file was opened: 
1 Input only 
2 Output only 
4 Random I/O 
16 Append only 
32 Internal use 
64 Future use 
128 Internal use 


Diskette file control block. 


Number of sectors read or written for 
sequential access. 

The last record number +1 read or written 
for random files. 


Number of bytes in sector when read or 
written. 


Number of bytes left in INPUT buffer. 
Reserved for future expansion. 


Device Number: 

0-9 Disks A: through J: 
255 KYBD: 

254 SCRN: 

253 LPT1: 

252 CAS1: 

251 COM1: 

250 COM2: 

249 LPT2: 

248 LPT3: 


Device width. 
Position in buffer for PRINT. 


Internal use during BLOAD/BSAVE. 
Not used for data files. 


Output position used during tab 
expansion. 
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51 128 BUFFER Physical data buffer. Used to transfer data 
between DOS and BASIC. Use this offset 


to examine data in sequential I/O mode. 


179 2 VRECL Variable length record size. Default is 
128. Set by length option in OPEN 
statement. 

181 2 PHYREC Current physical record number. 

183 2 LOGREC Current logical record number. 

185 1 sas Future use. 

186 2 OUTPOS Disk files only. Output position for 


PRINT, INPUT, and WRITE. 


188 n FIELD Actual FIELD data buffer. Size is 
determined by S:switch. VRECL bytes 
are transferred between BUFFER and 
FIELD on I/O operations. Use this offset 
to examine file data in random I/O mode. 


Example 1: 


100 X=VARPTR (Y) 


When executed, the variable X will contain an address that points to the storage 
space assigned to the variable Y. 


Example 2: 


10 OPEN "DATA.FIL" AS #1 

20 FCBADR = VARPTR (#1) 

30 DATADR = FCBADR+188 

40 AS = PEEK (DATADR) 

In line 20, FCBADR contains the start of FCB. 

In line 30, DATADR contains the address of the data buffer. 
In line 40, A$ contains the first byte in the data buffer. 


VARPTR$ Function 259 





VARPTR$ Function 


Purpose: 

To return a character form of the offset of a variable in memory. 
Syntax: 

VARPTR§ (variable) 

Comments: 


variable is the name of a variable that exists in the program. 


Note Assign all simple variables before calling VARPTR$ for an array 
element, because the array addresses change when a new simple variable is 
assigned. 


VARPTRS returns a three-byte string of the following form: 


Byte O0 Byte 1 Byte 2 


Byte 0 contains one of the following variable types: 


2 integer 

3 string 

4 single-precision 
8 double precision 


Byte 1 contains the 8086 address format, and is the least significant byte. 
Byte 2 contains the 8086 address format, and is the most significant byte. 
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Examples: 


100 X = USR(VARPTRS (Y) ) 
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VIEW Statement 
Purpose: 


To define a physical viewport limit from x1,y1 (upper-left x,y coordinates) to 
x2,y2 (lower-right x,y coordinates). 


Syntax: 


VIEW [[SCREEN]|[(x/,y/)-(x2,y2) [,[ful][ [border ]}]] 


Comments: 


RUN or VIEW with no arguments define the entire screen as the viewport. 
(xJ,y1) are the upper-left coordinates. 

(x2,y2) are the lower-right coordinates. 

The fill attribute lets you fill the view area with color. 

The border attribute lets you draw a line surrounding the viewport if space for 
a border is available. If border is omitted, no border is drawn. 

The x and y coordinates must be within the physical bounds of the screen and 
define the rectangle within the screen that graphics map into. The x and y 
coordinate pairs will be sorted, with the smallest values placed first. 

Points are plotted relative to the viewpoint if the screen argument is omitted; 
that is, x/ and y/ are added to the x and y coordinates before the point is 
plotted. 

It is possible to have a varied number of pairs of x and y. The only restriction is 
that x/ cannot equal x2, and y1 cannot equal y2. 

Points are plotted absolutely if the SCREEN argument is present. Only points 
within the current viewpoint will be plotted. 


When using VIEW, the CLS statement clears only the current viewport. To 
clear the entire screen, you must use VIEW to disable the viewports. Then use 
CLS to clear the screen. CLS does not move the cursor to home. Press cL- 
HOME to send the cursor home, and clear the screen. 
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Examples: 


The following defines a viewport such that the statement PSET(0,0),3 would 
set down a point at the physical screen location 10,10. 


VIEW (10,10)-(200,100) 


The following defines a viewport such that the point designated by the 
statement PSET(0,0),3 would not appear because 0,0 is outside of the viewport. 
PSET(10,10),3 would be within the viewport. 


VIEW SCREEN (10,10) -(200,100) 
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VIEW PRINT Statement 
Purpose: 


To set the boundaries of the screen text window. 


Syntax: 


VIEW PRINT [topline TO bottomline] 


Comments: 


VIEW PRINT without topline and bottomline parameters initializes the whole 
screen area as the text window. The whole screen area consists of lines 1 to 24; 
by default, line 25 is not used. 


Statements and functions that operate within the defined text window include 
CLS, LOCATE, PRINT, and SCREEN. 


The screen editor will limit functions such as scroll and cursor movement to the 
text window. 


For more information, see VIEW. 


264 GW-BASIC User’s Reference 





WAIT Statement 
Purpose: 


To suspend program execution while monitoring the status of a machine input 
port. 


Syntax: 


WAIT port number, nij] 


Comments: 


port number represents a valid machine port number within the range of 0 to 
65535. 


n and j are integer expressions in the range of 0 to 255. 


The WAIT statement causes execution to be suspended until a specified 
machine input port develops a specified bit pattern. 


The data read at the port is XORed with the integer expression j, and then 
ANDed with n. 


If the result is zero, Gw-Basic loops back and reads the data at the port again. 
If the result is nonzero, execution continues with the next statement. 


When executed, the WAIT statement tests the byte n for set bits. If any of the 
bits is set, then the program continues with the next statement in the program. 
WAIT does not wait for an entire pattern of bits to appear, but only for one of 
them to occur. 


It is possible to enter an infinite loop with the WAIT statement. You can exit 
the loop by pressing CTRL-BREAK, or by resetting the system. 


If j is omitted, zero is assumed. 


Examples: 


100 WAIT 32,2 


Suspends machine operation until port 32 receives 2 as input. 
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WHILE-WEND Statement 


Purpose: 


To execute a series of statements in a loop as long as a given condition is true. 


Syntax: 


WHILE expression 


[loop statements] 


WEND 
Comments: 


If expression is nonzero (true), loop statements are executed until the WEND 
statement is encountered. GW-BASIC then returns to the WHILE statement 
and checks expression. If it is still true, the process is repeated. 


If it is not true, execution resumes with the statement following the WEND 
statement. 

WHILE and WEND loops may be nested to any level. Each WEND matches 
the most recent WHILE. 


An unmatched WHILE statement causes a "WHILE without WEND" error. An 
unmatched WEND statement causes a "WEND without WHILE" error. 


266 GW-BASIC User's Reference 


Examples: 


90 ‘BUBBLE SORT ARRAY A$ 

100 FLIPS=1 

110 WHILE FLIPS 

115 FLIPS=0 

120 FOR N=1 TO J-1 

130 IF A$(N)>AS$(N+1) THEN SWAP A$ (N),AS$(N+1): 
FLIPS=1 

140 NEXT N 

150 WEND 
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WIDTH Statement 


Purpose: 


To set the printed line width in number of characters for the screen and line 
printer. 


Syntax: 


WIDTH size 
WIDTH file number, size 
WIDTH "dev", size 


Comments: 


size, an integer within the range of 0 to 255, is the new width. 
file number is the number of the file that is open. 


dev is a valid string expression identifying the device. Valid devices are 
SCRN:, LPT1:, LPT2:, LPT3:, COM1:, and COM2:. 


Changing Screen Width 


The following statements are used to set the screen width. Only a 40- or 80- 
column width is allowed. 


WIDTH size 
WIDTH "SCRN:" size 
See the SCREEN statement for more information. 


Changing SCREEN mode affects screen width only when moving between 
SCREEN 2 and SCREEN 1 or SCREEN 0. 


Note Changing the screen width clears the screen and sets the border screen 
color to black. 
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Changing Lineprinter Width 


The following WIDTH statement is used as a deferred width assignment for the 
lineprinter. This statement stores the new width value without actually 
changing the current width setting: 


WIDTH "LPT1:",size 

A statement of the following form recognizes this stored width value: 
OPEN "LPT1:" FOR OUTPUT AS number 

and uses it while the file is open: 

WIDTH file number,size 


If the file is open to Ipt1:, lineprinter width is immediately changed to the new 
size specified. This allows the width to be changed at will while the file is 
open. This form of WIDTH has meaning only for Ipt1:. After outputting the 
indicated number of characters from the open file, Gw-BAsic inserts a carriage 
return at the end of the line and wraps the output, if the width is less than the 
length of the record. 


Valid widths for the line printer are 1 through 255. 
Specifying WIDTH 255 for the line printer (Ipt1:) enables line wrapping. This 
has the effect of infinite width. 


Any value entered outside of these ranges results in an "Illegal function call" 
error. The previous value is retained. 


Using the WIDTH statement on a communications file causes a carriage retum 
to be sent after the number of characters specified by the size attribute. It does 
not alter either the receive or transmit buffer. 


Examples: 


10 WIDTH "LPT1:",75 
20 OPEN "LPT1:" FOR OUTPUT AS #1 


6020 WIDTH #1,40 


Line 10 stores a line printer width of 75 characters per line. 


WIDTH Statement 269 


Line 20 opens file #1 to the line printer and sets the width to 75 for subsequent 
PRINT #1, statements. 


Line 6020 changes the current line printer width to 40 characters per line. 
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WINDOW Statement 
Purpose: 


To draw lines, graphics, and objects in space not bounded by the physical limits 
of the screen. 


Syntax: 


WINDOW|[SCREEN](x/,y/)-(x2,y2)] 


Comments: 


(x1,y1), (x2,y2) are the coordinates defined by the user. These coordinates, 
called the world coordinates, may be any single-precision, floating-point 
number. They define the world coordinate space that graphics statements map 
into the physical coordinate space, as defined by the VIEW statement. 


WINDOW is the rectangular region in the world coordinate space. It allows 
zoom and pan. It allows the user to draw lines, graphics, and objects in space 
not bounded by the physical limits of the screen. To do this the user specifies 
the world coordinate pairs (xJ,y/) and (x2,y2.) Gw-Basic then converts the world 
coordinate pairs into the appropriate physical coordinate pairs for subsequent 
display within screen space. 

Window inverts, with the screen attribute omitted, the y coordinate on 
subsequent graphics statements. This places the (x/,y/) coordinate in the lower- 
left and the (x/,y2) coordinate in the upper-right of the screen. This allows the 
screen to be viewed in true Cartesian coordinates. 


The coordinates are not inverted when the SCREEN attribute is included. This 
places the (x/,y/) coordinate in the upper-left and the (x2,y2) coordinate in the 
lower-right corner of the screen. 


The WINDOW statement sorts the x and y argument pairs into ascending order. 
For example: 

WINDOW (50,50)-(10,10) 

becomes 

WINDOW (10,10)-(50,50) 
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Or 

WINDOW (-2,2)-(2,-2) 
becomes 

WINDOW (-2,-2)-(2,2) 


All coordinate pairs of x and y are valid, except that x7 cannot equal x2 and y/ 
cannot equal y2. 


WINDOW with no arguments disables previous window statements. 


Example 1: 


If you type the following: 


NEW 
SCREEN 2 


the screen uses the standard coordinate attributes as follows: 


0,0320,0639,0 


\/y increases 
320,100 


0,199320,100639,199 


Example 2: 


If you type the following: 
WINDOW (-1,-1)-(1,1) 
the screen uses the Cartesian coordinates as defined in the following statement: 


-1,10,11,1 
/\y increases 
0,0 


\/y decreases 
-1,10,11,1 
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Example 3: 


If you type the following: 
WINDOW SCREEN (-1,-1)-(1,1) 


the screen uses the non-inverted coordinate as defined in the following 
statement: 


-1,-10,-11,-1 
/y decreases 
0,0 

\/y increases 


-1,10,11,1 


RUN, SCREEN, and WINDOW with no attributes disable any WINDOW 
definitions and return the screen to its normal physical coordinates. 
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WRITE Statement 


Purpose: 


To output data to the screen. 
Syntax: 


WRITE[list of expressions] 


Comments: 


If list of expressions is omitted, a blank line is output. If list of expressions is 
included, the values of the expressions are output at the terminal. The 
expressions in the list may be numeric and/or string expressions, and must be 
separated by commas or semicolons. 

When printed items are output, each item will be separated from the last by a 


comma. Printed strings are delimited by double quotation marks. After the last 
item in the list is printed, Gw-BAsic inserts a carriage return/line feed. 

The difference between WRITE and PRINT is that WRITE inserts commas 
between displayed items and delimits strings with double quotation marks. 
Positive numbers are not preceded by blank spaces. 


WRITE outputs numeric values using the same format as the PRINT statement. 


Examples: 


10 A=80:B=90:C$="THAT’S ALL" 
20 WRITE A,B,C$ 

RUN 

80, 90,"THAT’S ALL" 

Ok 
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WRITE# Statement 


Purpose: 


To write data to a sequential file. 


Syntax: 


WRITE #filenum, list of expressions 


Comments: 


filenum is the number under which the file was opened for output. 


list of expressions is a list of string and/or numeric expressions separated by 
commas or semicolons. 


The WRITE# and PRINT# statements differ in that WRITE# inserts commas 
between the items as they are written and delimits strings with quotation marks, 
making explicit delimiters in the list unnecessary. Another difference is that 
WRITE+# does not put a blank in front of a positive number. After the last item 
in the list is written, a carriage return/line feed sequence is inserted. 


Examples: 


Let A$ = "CAMERA" and B$ = "93604-1". The following statement: 
WRITE#1,AS,BS$ 

writes the following image to disk: 

"CAMERA", "93604-1" 


A subsequent INPUTS statement, such as the following, would input 
"CAMERA" to A$ and "93604-1" to B$: 


INPUT#1,A$,BS 
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